cleanup of ActionController::Metal inline documentation

5 files changed, 50 insertions, 51 deletions

diff --git a/actionpack/lib/action_controller/metal.rb b/actionpack/lib/action_controller/metal.rb
index 2281c500c5..96ac138ba3 100644
--- a/actionpack/lib/action_controller/metal.rb
+++ b/actionpack/lib/action_controller/metal.rb
@@ -43,28 +43,28 @@ module ActionController
     end
   end
 
-  # ActionController::Metal provides a way to get a valid Rack application from a controller.
+  # Provides a way to get a valid Rack application from a controller.
   #
   # In AbstractController, dispatching is triggered directly by calling #process on a new controller.
-  # ActionController::Metal provides an #action method that returns a valid Rack application for a
-  # given action. Other rack builders, such as Rack::Builder, Rack::URLMap, and the Rails router,
-  # can dispatch directly to the action returned by FooController.action(:index).
+  # <tt>ActionController::Metal</tt> provides an <tt>action</tt> method that returns a valid Rack application for a
+  # given action. Other rack builders, such as Rack::Builder, Rack::URLMap, and the \Rails router,
+  # can dispatch directly to actions returned by controllers in your application.
   class Metal < AbstractController::Base
     abstract!
 
     attr_internal :env
 
     # Returns the last part of the controller's name, underscored, without the ending
-    # "Controller". For instance, MyApp::MyPostsController would return "my_posts" for
-    # controller_name
+    # <tt>Controller</tt>. For instance, PostsController returns <tt>posts</tt>.
+    # Namespaces are left out, so Admin::PostsController returns <tt>posts</tt> as well.
     #
     # ==== Returns
-    # String
+    # * <tt>string</tt>
     def self.controller_name
       @controller_name ||= self.name.demodulize.sub(/Controller$/, '').underscore
     end
 
-    # Delegates to the class' #controller_name
+    # Delegates to the class' <tt>controller_name</tt>
     def controller_name
       self.class.controller_name
     end
@@ -95,7 +95,7 @@ module ActionController
     # Basic implementations for content_type=, location=, and headers are
     # provided to reduce the dependency on the RackDelegation module
     # in Renderer and Redirector.
-
+    
     def content_type=(type)
       headers["Content-Type"] = type.to_s
     end
@@ -125,8 +125,7 @@ module ActionController
       super body
     end
 
-    # :api: private
-    def dispatch(name, request)
+    def dispatch(name, request) #:nodoc:
       @_request = request
       @_env = request.env
       @_env['action_controller.instance'] = self
@@ -134,8 +133,7 @@ module ActionController
       to_a
     end
 
-    # :api: private
-    def to_a
+    def to_a #:nodoc:
       response ? response.to_a : [status, headers, response_body]
     end
 
@@ -164,10 +162,10 @@ module ActionController
     # for the same action.
     #
     # ==== Parameters
-    # action<#to_s>:: An action name
+    # * <tt>action</tt> - An action name
     #
     # ==== Returns
-    # Proc:: A rack application
+    # * <tt>proc</tt> - A rack application
     def self.action(name, klass = ActionDispatch::Request)
       middleware_stack.build(name.to_s) do |env|
         new.dispatch(name, klass.new(env))
diff --git a/actionpack/lib/action_controller/metal/conditional_get.rb b/actionpack/lib/action_controller/metal/conditional_get.rb
index 61e7ece90d..797ad846f6 100644
--- a/actionpack/lib/action_controller/metal/conditional_get.rb
+++ b/actionpack/lib/action_controller/metal/conditional_get.rb
@@ -6,7 +6,7 @@ module ActionController
     include Head
 
     # Sets the etag, last_modified, or both on the response and renders a
-    # "304 Not Modified" response if the request is already fresh.
+    # <tt>304 Not Modified</tt> response if the request is already fresh.
     #
     # Parameters:
     # * <tt>:etag</tt>
@@ -21,7 +21,7 @@ module ActionController
     #   end
     #
     # This will render the show template if the request isn't sending a matching etag or
-    # If-Modified-Since header and just a "304 Not Modified" response if there's a match.
+    # If-Modified-Since header and just a <tt>304 Not Modified</tt> response if there's a match.
     #
     def fresh_when(options)
       options.assert_valid_keys(:etag, :last_modified, :public)
@@ -36,7 +36,7 @@ module ActionController
     # Sets the etag and/or last_modified on the response and checks it against
     # the client request. If the request doesn't match the options provided, the
     # request is considered stale and should be generated from scratch. Otherwise,
-    # it's fresh and we don't need to generate anything and a reply of "304 Not Modified" is sent.
+    # it's fresh and we don't need to generate anything and a reply of <tt>304 Not Modified</tt> is sent.
     #
     # Parameters:
     # * <tt>:etag</tt>
@@ -60,8 +60,8 @@ module ActionController
       !request.fresh?(response)
     end
 
-    # Sets a HTTP 1.1 Cache-Control header. Defaults to issuing a "private" instruction, so that
-    # intermediate caches shouldn't cache the response.
+    # Sets a HTTP 1.1 Cache-Control header. Defaults to issuing a <tt>private</tt> instruction, so that
+    # intermediate caches must not cache the response.
     #
     # Examples:
     #   expires_in 20.minutes
@@ -77,7 +77,7 @@ module ActionController
       response.cache_control[:extras] = options.map {|k,v| "#{k}=#{v}"}
     end
 
-    # Sets a HTTP 1.1 Cache-Control header of "no-cache" so no caching should occur by the browser or
+    # Sets a HTTP 1.1 Cache-Control header of <tt>no-cache</tt> so no caching should occur by the browser or
     # intermediate caches (like caching proxy servers).
     def expires_now #:doc:
       response.cache_control.replace(:no_cache => true)
diff --git a/actionpack/lib/action_controller/metal/helpers.rb b/actionpack/lib/action_controller/metal/helpers.rb
index e0bc47318a..4b6897c5dd 100644
--- a/actionpack/lib/action_controller/metal/helpers.rb
+++ b/actionpack/lib/action_controller/metal/helpers.rb
@@ -2,21 +2,21 @@ require 'active_support/core_ext/array/wrap'
 require 'active_support/core_ext/class/attribute'
 
 module ActionController
-  # The Rails framework provides a large number of helpers for working with +assets+, +dates+, +forms+,
-  # +numbers+ and model objects, to name a few. These helpers are available to all templates
+  # The \Rails framework provides a large number of helpers for working with assets, dates, forms,
+  # numbers and model objects, to name a few. These helpers are available to all templates
   # by default.
   #
-  # In addition to using the standard template helpers provided in the Rails framework, creating custom helpers to
+  # In addition to using the standard template helpers provided, creating custom helpers to
   # extract complicated logic or reusable functionality is strongly encouraged. By default, the controller will
   # include a helper whose name matches that of the controller, e.g., <tt>MyController</tt> will automatically
   # include <tt>MyHelper</tt>.
   #
-  # Additional helpers can be specified using the +helper+ class method in <tt>ActionController::Base</tt> or any
+  # Additional helpers can be specified using the +helper+ class method in ActionController::Base or any
   # controller which inherits from it.
   #
   # ==== Examples
-  # The +to_s+ method from the Time class can be wrapped in a helper method to display a custom message if
-  # the Time object is blank:
+  # The +to_s+ method from the \Time class can be wrapped in a helper method to display a custom message if
+  # a \Time object is blank:
   #
   #   module FormattedTimeHelper
   #     def format_time(time, format=:long, blank_message="&nbsp;")
@@ -71,12 +71,11 @@ module ActionController
       # Declares helper accessors for controller attributes. For example, the
       # following adds new +name+ and <tt>name=</tt> instance methods to a
       # controller and makes them available to the view:
-      #   helper_attr :name
       #   attr_accessor :name
+      #   helper_attr :name
       #
       # ==== Parameters
-      # *attrs<Array[String, Symbol]>:: Names of attributes to be converted
-      #   into helpers.
+      # * <tt>attrs</tt> - Names of attributes to be converted into helpers.
       def helper_attr(*attrs)
         attrs.flatten.each { |attr| helper_method(attr, "#{attr}=") }
       end
@@ -91,17 +90,16 @@ module ActionController
         # all helpers in helpers_dir.
         #
         # ==== Parameters
-        # args<Array[String, Symbol, Module, all]>:: A list of helpers
+        # * <tt>args</tt> - A list of helpers
         #
         # ==== Returns
-        # Array[Module]:: A normalized list of modules for the list of
-        #   helpers provided.
+        # * <tt>array</tt> - A normalized list of modules for the list of helpers provided.
         def modules_for_helpers(args)
           args += all_application_helpers if args.delete(:all)
           super(args)
         end
 
-        # Extract helper names from files in app/helpers/**/*_helper.rb
+        # Extract helper names from files in <tt>app/helpers/**/*_helper.rb</tt>
         def all_application_helpers
           helpers = []
           Array.wrap(helpers_path).each do |path|
diff --git a/actionpack/lib/action_controller/metal/hide_actions.rb b/actionpack/lib/action_controller/metal/hide_actions.rb
index 32d7a96701..b55c4643be 100644
--- a/actionpack/lib/action_controller/metal/hide_actions.rb
+++ b/actionpack/lib/action_controller/metal/hide_actions.rb
@@ -1,8 +1,7 @@
 require 'active_support/core_ext/class/attribute'
 
 module ActionController
-  # ActionController::HideActions adds the ability to prevent public methods on a controller
-  # to be called as actions.
+  # Adds the ability to prevent public methods on a controller to be called as actions.
   module HideActions
     extend ActiveSupport::Concern
 
@@ -23,7 +22,7 @@ module ActionController
       # Sets all of the actions passed in as hidden actions.
       #
       # ==== Parameters
-      # *args<#to_s>:: A list of actions
+      # * <tt>args</tt> - A list of actions
       def hide_action(*args)
         self.hidden_actions = hidden_actions.dup.merge(args.map(&:to_s)).freeze
       end
diff --git a/actionpack/lib/action_controller/metal/http_authentication.rb b/actionpack/lib/action_controller/metal/http_authentication.rb
index acd313b039..1d74521e4f 100644
--- a/actionpack/lib/action_controller/metal/http_authentication.rb
+++ b/actionpack/lib/action_controller/metal/http_authentication.rb
@@ -3,9 +3,9 @@ require 'active_support/core_ext/object/blank'
 
 module ActionController
   module HttpAuthentication
-    # Makes it dead easy to do HTTP Basic authentication.
+    # Makes it dead easy to do HTTP \Basic and \Digest authentication.
     #
-    # Simple Basic example:
+    # === Simple \Basic example
     #
     #   class PostsController < ApplicationController
     #     USER_NAME, PASSWORD = "dhh", "secret"
@@ -29,7 +29,9 @@ module ActionController
     #   end
     #
     #
-    # Here is a more advanced Basic example where only Atom feeds and the XML API is protected by HTTP authentication,
+    # === Advanced \Basic example
+    # 
+    # Here is a more advanced \Basic example where only Atom feeds and the XML API is protected by HTTP authentication,
     # the regular HTML interface is protected by a session approach:
     #
     #   class ApplicationController < ActionController::Base
@@ -69,7 +71,7 @@ module ActionController
     #     assert_equal 200, status
     #   end
     #
-    # Simple Digest example:
+    # === Simple \Digest example
     #
     #   require 'digest/md5'
     #   class PostsController < ApplicationController
@@ -95,18 +97,20 @@ module ActionController
     #       end
     #   end
     #
-    # NOTE: The +authenticate_or_request_with_http_digest+ block must return the user's password or the ha1 digest hash so the framework can appropriately
-    #       hash to check the user's credentials. Returning +nil+ will cause authentication to fail.
-    #       Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If
-    #       the password file or database is compromised, the attacker would be able to use the ha1 hash to
-    #       authenticate as the user at this +realm+, but would not have the user's password to try using at
-    #       other sites.
+    # === Notes
+    # 
+    # The +authenticate_or_request_with_http_digest+ block must return the user's password
+    # or the ha1 digest hash so the framework can appropriately hash to check the user's
+    # credentials. Returning +nil+ will cause authentication to fail.
     #
-    # On shared hosts, Apache sometimes doesn't pass authentication headers to
-    # FCGI instances. If your environment matches this description and you cannot
-    # authenticate, try this rule in your Apache setup:
+    # Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If
+    # the password file or database is compromised, the attacker would be able to use the ha1 hash to
+    # authenticate as the user at this +realm+, but would not have the user's password to try using at
+    # other sites.
     #
-    #   RewriteRule ^(.*)$ dispatch.fcgi [E=X-HTTP_AUTHORIZATION:%{HTTP:Authorization},QSA,L]
+    # In rare instances, web servers or front proxies strip authorization headers before
+    # they reach your application. You can debug this situation by logging all environment
+    # variables, and check for HTTP_AUTHORIZATION, amongst others.
     module Basic
       extend self