Improve documentation for ActionController::Helpers [jardeon] Closes #9359

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7363 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

actionpack/lib/action_controller/helpers.rb

@@ -18,27 +18,51 @@ module ActionController #:nodoc:
       end
     end
 
-    # The template helpers serve to relieve the templates from including the same inline code again and again. It's a
-    # set of standardized methods for working with forms (FormHelper), dates (DateHelper), texts (TextHelper), and
-    # Active Records (ActiveRecordHelper) that's available to all templates by default.
+    # The Rails framework provides a large number of helpers for working with +assets+, +dates+, +forms+, 
+    # +numbers+ and <tt>Active Record objects</tt>, to name a few.  These helpers are available to all templates
+    # by default.
     #
-    # It's also really easy to make your own helpers and it's much encouraged to keep the template files free
-    # from complicated logic. It's even encouraged to bundle common compositions of methods from other helpers
-    # (often the common helpers) as they're used by the specific application.
+    # In addition to using the standard template helpers provided in the Rails framework, 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
+    # controller which inherits from it.  
     #
-    #   module MyHelper
-    #     def hello_world() "hello world" end
+    # ==== 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:
+    #
+    #   module FormattedTimeHelper
+    #     def format_time(time, format=:long, blank_message="&nbsp;")
+    #       time.blank? ? blank_message : time.to_s(format)
+    #     end
     #   end
     #
-    # MyHelper can now be included in a controller, like this:
+    # +FormattedTimeHelper+ can now be included in a controller, using the +helper+ class method:
     #
-    #   class MyController < ActionController::Base
-    #     helper :my_helper
+    #   class EventsController < ActionController::Base
+    #     helper FormattedTimeHelper
+    #     def index
+    #       @events = Event.find(:all)
+    #     end
     #   end
     #
-    # ...and, same as above, used in any template rendered from MyController, like this:
+    # Then, in any view rendered by <tt>EventController</tt>, the <tt>format_time</tt> method can be called:
+    #
+    #   <% @events.each do |event| -%>
+    #     <p>
+    #       <% format_time(event.time, :short, "N/A") %> | <%= event.name %> 
+    #     </p>
+    #   <% end -%>
+    #
+    # Finally, assuming we have two event instances, one which has a time and one which does not, 
+    # the output might look like this:
+    #
+    #   23 Aug 11:30 | Carolina Railhawks Soccer Match 
+    #   N/A | Carolina Railhaws Training Workshop
     #
-    # Let's hear what the helper has to say: <tt><%= hello_world %></tt>
     module ClassMethods
       # Makes all the (instance) methods in the helper module available to templates rendered through this controller.
       # See ActionView::Helpers (link:classes/ActionView/Helpers.html) for more about making your own helper modules
@@ -47,22 +71,41 @@ module ActionController #:nodoc:
         master_helper_module.send(:include, helper_module)
       end
 
-      # Declare a helper:
+      # The +helper+ class method can take a series of helper module names, a block, or both.
       #
-      #   helper :foo
-      # requires 'foo_helper' and includes FooHelper in the template class.
+      # * <tt>*args</tt>: One or more +Modules+, +Strings+ or +Symbols+, or the special symbol <tt>:all</tt>.
+      # * <tt>&block</tt>: A block defining helper methods.
+      # 
+      # ==== Examples
+      # When the argument is a +String+ or +Symbol+, the method will provide the "_helper" suffix, require the file 
+      # and include the module in the template class.  The second form illustrates how to include custom helpers 
+      # when working with namespaced controllers, or other cases where the file containing the helper definition is not
+      # in one of Rails' standard load paths:
+      #   helper :foo             # => requires 'foo_helper' and includes FooHelper
+      #   helper 'resources/foo'  # => requires 'resources/foo_helper' and includes Resources::FooHelper
       #
-      #   helper FooHelper
-      # includes FooHelper in the template class.
-      #
-      #   helper { def foo() "#{bar} is the very best" end }
-      # evaluates the block in the template class, adding method #foo.
-      #
-      #   helper(:three, BlindHelper) { def mice() 'mice' end }
-      # does all three.
+      # When the argument is a +Module+, it will be included directly in the template class.
+      #   helper FooHelper # => includes FooHelper
       #
+      # When the argument is the symbol <tt>:all</tt>, the controller will includes all helpers from 
+      # <tt>app/views/helpers/**/*.rb</tt> under RAILS_ROOT
       #   helper :all
-      # includes all helpers from app/views/helpers/**/*.rb under RAILS_ROOT
+      #
+      # Additionally, the +helper+ class method can receive and evaluate a block, making the methods defined available 
+      # to the template.
+      #   # One line
+      #   helper { def hello() "Hello, world!" end }
+      #   # Multi-line
+      #   helper do
+      #     def foo(bar) 
+      #       "#{bar} is the very best" 
+      #     end
+      #   end
+      # 
+      # Finally, all the above styles can be mixed together, and the helper method can be invokved with a mix of
+      # +symbols+, +strings+, +modules+ and blocks.
+      #   helper(:three, BlindHelper) { def mice() 'mice' end }
+      #
       def helper(*args, &block)
         args.flatten.each do |arg|
           case arg
@@ -97,9 +140,13 @@ module ActionController #:nodoc:
       end
 
       # Declare a controller method as a helper.  For example,
-      #   helper_method :link_to
-      #   def link_to(name, options) ... end
-      # makes the link_to controller method available in the view.
+      #   class ApplicationController < ActionController::Base
+      #     helper_method :current_user
+      #     def current_user
+      #       @current_user ||= User.find(session[:user])
+      #     end
+      #   end
+      # makes the +current_user+ controller method available in the view.
       def helper_method(*methods)
         methods.flatten.each do |method|
           master_helper_module.module_eval <<-end_eval