Better docs for AbstractController

Fixes internal links, adds examples and set fixed-width fonts.

[ci skip]

3 files changed, 24 insertions, 18 deletions

diff --git a/actionpack/lib/abstract_controller/base.rb b/actionpack/lib/abstract_controller/base.rb
index 51c661f735..2c8a67db09 100644
--- a/actionpack/lib/abstract_controller/base.rb
+++ b/actionpack/lib/abstract_controller/base.rb
@@ -12,7 +12,7 @@ module AbstractController
   class ActionNotFound < StandardError
   end
 
-  # <tt>AbstractController::Base</tt> is a low-level API. Nobody should be
+  # AbstractController::Base is a low-level API. Nobody should be
   # using it directly, and subclasses (like ActionController::Base) are
   # expected to provide their own +render+ method, since rendering means
   # different things depending on the context.
@@ -69,9 +69,9 @@ module AbstractController
 
       # A list of method names that should be considered actions. This
       # includes all public instance methods on a controller, less
-      # any internal methods (see #internal_methods), adding back in
+      # any internal methods (see internal_methods), adding back in
       # any methods that are internal, but still exist on the class
-      # itself. Finally, #hidden_actions are removed.
+      # itself. Finally, hidden_actions are removed.
       #
       # ==== Returns
       # * <tt>Set</tt> - A set of all methods that should be considered actions.
@@ -92,15 +92,19 @@ module AbstractController
       end
 
       # action_methods are cached and there is sometimes need to refresh
-      # them. clear_action_methods! allows you to do that, so next time
+      # them. ::clear_action_methods! allows you to do that, so next time
       # you run action_methods, they will be recalculated
       def clear_action_methods!
         @action_methods = nil
       end
 
       # Returns the full controller name, underscored, without the ending Controller.
-      # For instance, MyApp::MyPostsController would return "my_app/my_posts" for
-      # controller_path.
+      #
+      #   class MyApp
+      #     MyPostsController < AbstractController::Base
+      #     end
+      #   end
+      #   MyApp::MyPostsController.controller_path # => "my_app/my_posts"
       #
       # ==== Returns
       # * <tt>String</tt>
@@ -137,12 +141,12 @@ module AbstractController
       process_action(action_name, *args)
     end
 
-    # Delegates to the class' #controller_path
+    # Delegates to the class' ::controller_path
     def controller_path
       self.class.controller_path
     end
 
-    # Delegates to the class' #action_methods
+    # Delegates to the class' ::action_methods
     def action_methods
       self.class.action_methods
     end
diff --git a/actionpack/lib/abstract_controller/callbacks.rb b/actionpack/lib/abstract_controller/callbacks.rb
index ca5c80cd71..0d2f18279b 100644
--- a/actionpack/lib/abstract_controller/callbacks.rb
+++ b/actionpack/lib/abstract_controller/callbacks.rb
@@ -22,10 +22,11 @@ module AbstractController
     end
 
     module ClassMethods
-      # If :only or :except are used, convert the options into the
-      # :unless and :if options of ActiveSupport::Callbacks.
-      # The basic idea is that :only => :index gets converted to
-      # :if => proc {|c| c.action_name == "index" }.
+      # If +:only+ or +:except+ are used, convert the options into the
+      # +:if+ and +:unless+ options of ActiveSupport::Callbacks.
+      #
+      # The basic idea is that <tt>:only => :index</tt> gets converted to
+      # <tt>:if => proc {|c| c.action_name == "index" }</tt>.
       #
       # ==== Options
       # * <tt>only</tt>   - The callback should be run only for this action
diff --git a/actionpack/lib/abstract_controller/rendering.rb b/actionpack/lib/abstract_controller/rendering.rb
index 9d10140ed2..585d20c56c 100644
--- a/actionpack/lib/abstract_controller/rendering.rb
+++ b/actionpack/lib/abstract_controller/rendering.rb
@@ -18,7 +18,7 @@ module AbstractController
     include ActionView::ViewPaths
 
     # Normalize arguments, options and then delegates render_to_body and
-    # sticks the result in self.response_body.
+    # sticks the result in <tt>self.response_body</tt>.
     # :api: public
     def render(*args, &block)
       options = _normalize_render(*args, &block)
@@ -30,11 +30,11 @@ module AbstractController
     # Raw rendering of a template to a string.
     #
     # It is similar to render, except that it does not
-    # set the response_body and it should be guaranteed
+    # set the +response_body+ and it should be guaranteed
     # to always return a string.
     #
-    # If a component extends the semantics of response_body
-    # (as Action Controller extends it to be anything that
+    # If a component extends the semantics of +response_body+
+    # (as ActionController extends it to be anything that
     # responds to the method each), this method needs to be
     # overridden in order to still return a string.
     # :api: plugin
@@ -73,8 +73,9 @@ module AbstractController
       }
     end
 
-    # Normalize args by converting render "foo" to render :action => "foo" and
-    # render "foo/bar" to render :file => "foo/bar".
+    # Normalize args by converting <tt>render "foo"</tt> to
+    # <tt>render :action => "foo"</tt> and <tt>render "foo/bar"</tt> to
+    # <tt>render :file => "foo/bar"</tt>.
     # :api: plugin
     def _normalize_args(action=nil, options={})
       if action.is_a? Hash