Document controller APIs (#1479)

When reviewing #1478, it became apparent to me that controller APIs such as `resource_params` are not documented.

I think they should be part of Administrate's interface, and as such should be documented. Here's some documentation.

Additionally:

* Changed the example for `update` so that it's more useful. The current example doesn't render or redirect, so it may cause confusion to someone trying to emulate it.
* Mentioned `requested_resource` too.
* Fixed the indent for the `scoped_resource` example.

lib/generators/administrate/dashboard/templates/controller.rb.erb

@@ -4,9 +4,8 @@ module <%= namespace.classify %>
     # For example, you may want to send an email after a foo is updated.
     #
     # def update
-    #   foo = Foo.find(params[:id])
-    #   foo.update(params[:foo])
-    #   send_foo_updated_email
+    #   super
+    #   send_foo_updated_email(requested_resource)
     # end
 
     # Override this method to specify custom lookup behavior.
@@ -17,15 +16,28 @@ module <%= namespace.classify %>
     #   Foo.find_by!(slug: param)
     # end
 
+    # The result of this lookup will be available as `requested_resource`
+
     # Override this if you have certain roles that require a subset
     # this will be used to set the records shown on the `index` action.
     #
     # def scoped_resource
-    #  if current_user.super_admin?
-    #    resource_class
-    #  else
-    #    resource_class.with_less_stuff
-    #  end
+    #   if current_user.super_admin?
+    #     resource_class
+    #   else
+    #     resource_class.with_less_stuff
+    #   end
+    # end
+
+    # Override `resource_params` if you want to transform the submitted
+    # data before it's persisted. For example, the following would turn all
+    # empty values into nil values. It uses other APIs such as `resource_class`
+    # and `dashboard`:
+    #
+    # def resource_params
+    #   params.require(resource_class.model_name.param_key).
+    #     permit(dashboard.permitted_attributes).
+    #     transform_values { |value| value == "" ? nil : value }
     # end
 
     # See https://administrate-prototype.herokuapp.com/customizing_controller_actions