Merge commit 'mainstream/master'

Conflicts:
	actionpack/lib/action_controller.rb
	actionpack/lib/action_controller/base/base.rb
	actionpack/lib/action_view/template/path.rb
	activesupport/lib/active_support/json/encoders/hash.rb

8 files changed, 366 insertions, 115 deletions

diff --git a/actionpack/lib/action_controller/abstract/base.rb b/actionpack/lib/action_controller/abstract/base.rb
index 87083a4d79..a19a236ef7 100644
--- a/actionpack/lib/action_controller/abstract/base.rb
+++ b/actionpack/lib/action_controller/abstract/base.rb
@@ -1,53 +1,65 @@
 require 'active_support/core_ext/module/attr_internal'
 
 module AbstractController
-  class Error < StandardError; end
-
-  class DoubleRenderError < Error
-    DEFAULT_MESSAGE = "Render and/or redirect were called multiple times in this action. Please note that you may only call render OR redirect, and at most once per action. Also note that neither redirect nor render terminate execution of the action, so if you want to exit an action after redirecting, you need to do something like \"redirect_to(...) and return\"."
-
-    def initialize(message = nil)
-      super(message || DEFAULT_MESSAGE)
-    end
-  end
 
   class Base
     attr_internal :response_body
-    attr_internal :response_obj
     attr_internal :action_name
 
     class << self
       attr_reader :abstract
+      alias_method :abstract?, :abstract
 
+      # Define a controller as abstract. See internal_methods for more
+      # details.
       def abstract!
         @abstract = true
       end
 
-      alias_method :abstract?, :abstract
-
       def inherited(klass)
-        ::AbstractController::Base.subclasses << klass.to_s
+        ::AbstractController::Base.descendants << klass.to_s
         super
       end
 
-      def subclasses
-        @subclasses ||= []
+      # A list of all descendents of AbstractController::Base. This is
+      # useful for initializers which need to add behavior to all controllers.
+      def descendants
+        @descendants ||= []
       end
 
+      # A list of all internal methods for a controller. This finds the first
+      # abstract superclass of a controller, and gets a list of all public
+      # instance methods on that abstract class. Public instance methods of
+      # a controller would normally be considered action methods, so we
+      # are removing those methods on classes declared as abstract
+      # (ActionController::Http and ActionController::Base are defined
+      # as abstract)
       def internal_methods
         controller = self
         controller = controller.superclass until controller.abstract?
         controller.public_instance_methods(true)
       end
 
-      def process(action)
-        new.process(action.to_s)
-      end
-
+      # The list of hidden actions to an empty Array. Defaults to an
+      # empty Array. This can be modified by other modules or subclasses
+      # to specify particular actions as hidden.
+      #
+      # ==== Returns
+      # Array[String]:: An array of method names that should not be
+      #                 considered actions.
       def hidden_actions
         []
       end
 
+      # 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 methods that are internal, but still exist on the class
+      # itself. Finally, #hidden_actions are removed.
+      #
+      # ==== Returns
+      # Array[String]:: A list of all methods that should be considered
+      #                 actions.
       def action_methods
         @action_methods ||=
           # All public instance methods of this class, including ancestors
@@ -63,10 +75,14 @@ module AbstractController
 
     abstract!
 
-    def initialize
-      self.response_obj = {}
-    end
-
+    # Calls the action going through the entire action dispatch stack.
+    # 
+    # The actual method that is called is determined by calling
+    # #method_for_action. If no method can handle the action, then an
+    # ActionNotFound error is raised.
+    #
+    # ==== Returns
+    # self
     def process(action)
       @_action_name = action_name = action.to_s
 
@@ -79,33 +95,63 @@ module AbstractController
     end
 
   private
-    def action_methods
-      self.class.action_methods
-    end
-
-    def action_method?(action)
-      action_methods.include?(action)
+    # Returns true if the name can be considered an action. This can
+    # be overridden in subclasses to modify the semantics of what
+    # can be considered an action.
+    #
+    # ==== Parameters
+    # name<String>:: The name of an action to be tested
+    #
+    # ==== Returns
+    # TrueClass, FalseClass
+    def action_method?(name)
+      self.class.action_methods.include?(name)
     end
 
-    # It is possible for respond_to?(action_name) to be false and
-    # respond_to?(:action_missing) to be false if respond_to_action?
-    # is overridden in a subclass. For instance, ActionController::Base
-    # overrides it to include the case where a template matching the
-    # action_name is found.
+    # Call the action. Override this in a subclass to modify the
+    # behavior around processing an action. This, and not #process,
+    # is the intended way to override action dispatching.
     def process_action(method_name)
       send_action(method_name)
     end
 
+    # Actually call the method associated with the action. Override
+    # this method if you wish to change how action methods are called,
+    # not to add additional behavior around it. For example, you would
+    # override #send_action if you want to inject arguments into the
+    # method.
     alias send_action send
 
+    # If the action name was not found, but a method called "action_missing"
+    # was found, #method_for_action will return "_handle_action_missing".
+    # This method calls #action_missing with the current action name.
     def _handle_action_missing
       action_missing(@_action_name)
     end
 
-    # Override this to change the conditions that will raise an
-    # ActionNotFound error. If you accept a difference case,
-    # you must handle it by also overriding process_action and
-    # handling the case.
+    # Takes an action name and returns the name of the method that will
+    # handle the action. In normal cases, this method returns the same
+    # name as it receives. By default, if #method_for_action receives
+    # a name that is not an action, it will look for an #action_missing
+    # method and return "_handle_action_missing" if one is found.
+    #
+    # Subclasses may override this method to add additional conditions
+    # that should be considered an action. For instance, an HTTP controller
+    # with a template matching the action name is considered to exist.
+    #
+    # If you override this method to handle additional cases, you may
+    # also provide a method (like _handle_method_missing) to handle
+    # the case.
+    #
+    # If none of these conditions are true, and method_for_action
+    # returns nil, an ActionNotFound exception will be raised.
+    #
+    # ==== Parameters
+    # action_name<String>:: An action name to find a method name for
+    #
+    # ==== Returns
+    # String:: The name of the method that handles the action
+    # nil::    No method name could be found. Raise ActionNotFound.
     def method_for_action(action_name)
       if action_method?(action_name) then action_name
       elsif respond_to?(:action_missing, true) then "_handle_action_missing"
diff --git a/actionpack/lib/action_controller/abstract/benchmarker.rb b/actionpack/lib/action_controller/abstract/benchmarker.rb
index 07294cede3..58e9564c2f 100644
--- a/actionpack/lib/action_controller/abstract/benchmarker.rb
+++ b/actionpack/lib/action_controller/abstract/benchmarker.rb
@@ -5,6 +5,16 @@ module AbstractController
     include Logger
 
     module ClassMethods
+      # Execute the passed in block, timing the duration of the block in ms.
+      #
+      # ==== Parameters
+      # title<#to_s>:: The title of block to benchmark
+      # log_level<Integer>:: A valid log level. Defaults to Logger::DEBUG
+      # use_silence<TrueClass, FalseClass>:: Whether or not to silence the
+      #   logger for the duration of the block.
+      #
+      # ==== Returns
+      # Object:: The result of the block
       def benchmark(title, log_level = ::Logger::DEBUG, use_silence = true)
         if logger && logger.level >= log_level
           result = nil
diff --git a/actionpack/lib/action_controller/abstract/callbacks.rb b/actionpack/lib/action_controller/abstract/callbacks.rb
index c6d3413c30..0d5161c80e 100644
--- a/actionpack/lib/action_controller/abstract/callbacks.rb
+++ b/actionpack/lib/action_controller/abstract/callbacks.rb
@@ -2,12 +2,17 @@ module AbstractController
   module Callbacks
     extend ActiveSupport::Concern
 
+    # Uses ActiveSupport::NewCallbacks as the base functionality. For
+    # more details on the whole callback system, read the documentation
+    # for ActiveSupport::NewCallbacks.
     include ActiveSupport::NewCallbacks
 
     included do
       define_callbacks :process_action, "response_body"
     end
 
+    # Override AbstractController::Base's process_action to run the
+    # process_action callbacks around the normal behavior.
     def process_action(method_name)
       _run_process_action_callbacks(method_name) do
         super
@@ -15,6 +20,17 @@ module AbstractController
     end
 
     module ClassMethods
+      # If :only or :accept are used, convert the options into the
+      # primitive form (:per_key) used by ActiveSupport::Callbacks.
+      # The basic idea is that :only => :index gets converted to
+      # :if => proc {|c| c.action_name == "index" }, but that the
+      # proc is only evaluated once per action for the lifetime of
+      # a Rails process.
+      #
+      # ==== Options
+      # :only<#to_s>:: The callback should be run only for this action
+      # :except<#to_s>:: The callback should be run for all actions
+      #   except this action
       def _normalize_callback_options(options)
         if only = options[:only]
           only = Array(only).map {|o| "action_name == '#{o}'"}.join(" || ")
@@ -26,35 +42,69 @@ module AbstractController
         end
       end
 
+      # Skip before, after, and around filters matching any of the names
+      #
+      # ==== Parameters
+      # *names<Object>:: A list of valid names that could be used for
+      #   callbacks. Note that skipping uses Ruby equality, so it's
+      #   impossible to skip a callback defined using an anonymous proc
+      #   using #skip_filter
+      def skip_filter(*names, &blk)
+        skip_before_filter(*names)
+        skip_after_filter(*names)
+        skip_around_filter(*names)
+      end
+
+      # Take callback names and an optional callback proc, normalize them,
+      # then call the block with each callback. This allows us to abstract
+      # the normalization across several methods that use it.
+      #
+      # ==== Parameters
+      # callbacks<Array[*Object, Hash]>:: A list of callbacks, with an optional
+      #   options hash as the last parameter.
+      # block<Proc>:: A proc that should be added to the callbacks.
+      #
+      # ==== Block Parameters
+      # name<Symbol>:: The callback to be added
+      # options<Hash>:: A list of options to be used when adding the callback
+      def _insert_callbacks(callbacks, block)
+        options = callbacks.last.is_a?(Hash) ? callbacks.pop : {}
+        _normalize_callback_options(options)
+        callbacks.push(block) if block
+        callbacks.each do |callback|
+          yield callback, options
+        end
+      end
+
+      # set up before_filter, prepend_before_filter, skip_before_filter, etc.
+      # for each of before, after, and around.
       [:before, :after, :around].each do |filter|
         class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+          # Append a before, after or around filter. See _insert_callbacks
+          # for details on the allowed parameters.
           def #{filter}_filter(*names, &blk)
-            options = names.last.is_a?(Hash) ? names.pop : {}
-            _normalize_callback_options(options)
-            names.push(blk) if block_given?
-            names.each do |name|
-              process_action_callback(:#{filter}, name, options)
+            _insert_callbacks(names, blk) do |name, options|
+              set_callback(:process_action, :#{filter}, name, options)
             end
           end
 
+          # Prepend a before, after or around filter. See _insert_callbacks
+          # for details on the allowed parameters.
           def prepend_#{filter}_filter(*names, &blk)
-            options = names.last.is_a?(Hash) ? names.pop : {}
-            _normalize_callback_options(options)
-            names.push(blk) if block_given?
-            names.each do |name|
-              process_action_callback(:#{filter}, name, options.merge(:prepend => true))
+            _insert_callbacks(names, blk) do |name, options|
+              set_callback(:process_action, :#{filter}, name, options.merge(:prepend => true))
             end
           end
 
+          # Skip a before, after or around filter. See _insert_callbacks
+          # for details on the allowed parameters.
           def skip_#{filter}_filter(*names, &blk)
-            options = names.last.is_a?(Hash) ? names.pop : {}
-            _normalize_callback_options(options)
-            names.push(blk) if block_given?
-            names.each do |name|
-              skip_process_action_callback(:#{filter}, name, options)
+            _insert_callbacks(names, blk) do |name, options|
+              skip_callback(:process_action, :#{filter}, name, options)
             end
           end
 
+          # *_filter is the same as append_*_filter
           alias_method :append_#{filter}_filter, :#{filter}_filter
         RUBY_EVAL
       end
diff --git a/actionpack/lib/action_controller/abstract/exceptions.rb b/actionpack/lib/action_controller/abstract/exceptions.rb
index 2f6c55f068..b671516de1 100644
--- a/actionpack/lib/action_controller/abstract/exceptions.rb
+++ b/actionpack/lib/action_controller/abstract/exceptions.rb
@@ -1,3 +1,12 @@
 module AbstractController
+  class Error < StandardError; end
   class ActionNotFound < StandardError; end
+
+  class DoubleRenderError < Error
+    DEFAULT_MESSAGE = "Render and/or redirect were called multiple times in this action. Please note that you may only call render OR redirect, and at most once per action. Also note that neither redirect nor render terminate execution of the action, so if you want to exit an action after redirecting, you need to do something like \"redirect_to(...) and return\"."
+
+    def initialize(message = nil)
+      super(message || DEFAULT_MESSAGE)
+    end
+  end
 end
diff --git a/actionpack/lib/action_controller/abstract/helpers.rb b/actionpack/lib/action_controller/abstract/helpers.rb
index 0a2776de9c..6b73f887c1 100644
--- a/actionpack/lib/action_controller/abstract/helpers.rb
+++ b/actionpack/lib/action_controller/abstract/helpers.rb
@@ -5,33 +5,26 @@ module AbstractController
     include Renderer
 
     included do
-      extlib_inheritable_accessor :master_helper_module
-      self.master_helper_module = Module.new
+      extlib_inheritable_accessor(:_helpers) { Module.new }
     end
 
+    # Override AbstractController::Renderer's _action_view to include the
+    # helper module for this class into its helpers module.
     def _action_view
-      @_action_view ||= begin
-        av = super
-        av.helpers.send(:include, master_helper_module)
-        av
-      end
+      @_action_view ||= super.tap { |av| av.helpers.include(_helpers) }
     end
 
     module ClassMethods
+      # When a class is inherited, wrap its helper module in a new module.
+      # This ensures that the parent class's module can be changed
+      # independently of the child class's.
       def inherited(klass)
-        klass.master_helper_module = Module.new
-        klass.master_helper_module.__send__ :include, master_helper_module
+        helpers = _helpers
+        klass._helpers = Module.new { include helpers }
 
         super
       end
 
-      # 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
-      # available to the templates.
-      def add_template_helper(mod)
-        master_helper_module.module_eval { include mod }
-      end
-
       # Declare a controller method as a helper. For example, the following
       # makes the +current_user+ controller method available to the view:
       #   class ApplicationController < ActionController::Base
@@ -48,9 +41,13 @@ module AbstractController
       #
       # In a view:
       #  <% if logged_in? -%>Welcome, <%= current_user.name %><% end -%>
+      #
+      # ==== Parameters
+      # meths<Array[#to_s]>:: The name of a method on the controller
+      #   to be made available on the view.
       def helper_method(*meths)
         meths.flatten.each do |meth|
-          master_helper_module.class_eval <<-ruby_eval, __FILE__, __LINE__ + 1
+          _helpers.class_eval <<-ruby_eval, __FILE__, __LINE__ + 1
             def #{meth}(*args, &blk)
               controller.send(%(#{meth}), *args, &blk)
             end
@@ -58,6 +55,14 @@ module AbstractController
         end
       end
 
+      # Make a number of helper modules part of this class' default
+      # helpers.
+      #
+      # ==== Parameters
+      # *args<Array[Module]>:: Modules to be included
+      # block<Block>:: Evalulate the block in the context
+      #   of the helper module. Any methods defined in the block
+      #   will be helpers.
       def helper(*args, &block)
         args.flatten.each do |arg|
           case arg
@@ -65,7 +70,18 @@ module AbstractController
             add_template_helper(arg)
           end
         end
-        master_helper_module.module_eval(&block) if block_given?
+        _helpers.module_eval(&block) if block_given?
+      end
+
+      private
+      # Makes all the (instance) methods in the helper module available to templates
+      # rendered through this controller.
+      #
+      # ==== Parameters
+      # mod<Module>:: The module to include into the current helper module
+      #   for the class
+      def add_template_helper(mod)
+        _helpers.module_eval { include mod }
       end
     end
   end
diff --git a/actionpack/lib/action_controller/abstract/layouts.rb b/actionpack/lib/action_controller/abstract/layouts.rb
index 273063f74b..2ac4e6068a 100644
--- a/actionpack/lib/action_controller/abstract/layouts.rb
+++ b/actionpack/lib/action_controller/abstract/layouts.rb
@@ -5,16 +5,31 @@ module AbstractController
     include Renderer
 
     included do
-      extlib_inheritable_accessor :_layout_conditions
-      self._layout_conditions = {}
+      extlib_inheritable_accessor(:_layout_conditions) { Hash.new }
     end
 
     module ClassMethods
-      def layout(layout, conditions = {})
-        unless [String, Symbol, FalseClass, NilClass].include?(layout.class)
-          raise ArgumentError, "Layouts must be specified as a String, Symbol, false, or nil"
-        end
+      def inherited(klass)
+        super
+        klass._write_layout_method
+      end
 
+      # Specify the layout to use for this class.
+      #
+      # If the specified layout is a:
+      # String:: the String is the template name
+      # Symbol:: call the method specified by the symbol, which will return
+      #   the template name
+      # false::  There is no layout
+      # true::   raise an ArgumentError
+      #
+      # ==== Parameters
+      # layout<String, Symbol, false)>:: The layout to use.
+      #
+      # ==== Options (conditions)
+      # :only<#to_s, Array[#to_s]>:: A list of actions to apply this layout to.
+      # :except<#to_s, Array[#to_s]>:: Apply this layout to all actions but this one
+      def layout(layout, conditions = {})
         conditions.each {|k, v| conditions[k] = Array(v).map {|a| a.to_s} }
         self._layout_conditions = conditions
 
@@ -22,6 +37,11 @@ module AbstractController
         _write_layout_method
       end
 
+      # If no layout is supplied, look for a template named the return
+      # value of this method.
+      #
+      # ==== Returns
+      # String:: A template name
       def _implied_layout_name
         name.underscore
       end
@@ -29,23 +49,31 @@ module AbstractController
       # Takes the specified layout and creates a _layout method to be called
       # by _default_layout
       #
-      # If the specified layout is a:
-      # String:: return the string
-      # Symbol:: call the method specified by the symbol
-      # false::  return nil
-      # none::   If a layout is found in the view paths with the controller's
-      #          name, return that string. Otherwise, use the superclass'
-      #          layout (which might also be implied)
+      # If there is no explicit layout specified:
+      # If a layout is found in the view paths with the controller's
+      # name, return that string. Otherwise, use the superclass'
+      # layout (which might also be implied)
       def _write_layout_method
         case @_layout
         when String
           self.class_eval %{def _layout(details) #{@_layout.inspect} end}
         when Symbol
-          self.class_eval %{def _layout(details) #{@_layout} end}
+          self.class_eval <<-ruby_eval, __FILE__, __LINE__ + 1
+            def _layout(details)
+              #{@_layout}.tap do |layout|
+                unless layout.is_a?(String) || !layout
+                  raise ArgumentError, "Your layout method :#{@_layout} returned \#{layout}. It " \
+                    "should have returned a String, false, or nil"
+                end
+              end
+            end
+          ruby_eval
         when false
           self.class_eval %{def _layout(details) end}
-        else
-          self.class_eval %{
+        when true
+          raise ArgumentError, "Layouts must be specified as a String, Symbol, false, or nil"
+        when nil
+          self.class_eval <<-ruby_eval, __FILE__, __LINE__ + 1
             def _layout(details)
               if view_paths.find_by_parts?("#{_implied_layout_name}", details, "layouts")
                 "#{_implied_layout_name}"
@@ -53,33 +81,55 @@ module AbstractController
                 super
               end
             end
-          }
+          ruby_eval
         end
+        self.class_eval { private :_layout }
       end
     end
 
   private
-    # This will be overwritten
-    def _layout(details)
-    end
+    # This will be overwritten by _write_layout_method
+    def _layout(details) end
 
-    # :api: plugin
-    # ====
-    # Override this to mutate the inbound layout name
+    # Determine the layout for a given name and details.
+    #
+    # ==== Parameters
+    # name<String>:: The name of the template
+    # details<Hash{Symbol => Object}>:: A list of details to restrict
+    #   the lookup to. By default, layout lookup is limited to the
+    #   formats specified for the current request.
     def _layout_for_name(name, details = {:formats => formats})
-      unless [String, FalseClass, NilClass].include?(name.class)
-        raise ArgumentError, "String, false, or nil expected; you passed #{name.inspect}"
-      end
-
-      name && view_paths.find_by_parts(name, details, _layout_prefix(name))
+      name && _find_by_parts(name, details)
     end
 
-    # TODO: Decide if this is the best hook point for the feature
-    def _layout_prefix(name)
-      "layouts"
+    # Take in the name and details and find a Template.
+    #
+    # ==== Parameters
+    # name<String>:: The name of the template to retrieve
+    # details<Hash>:: A list of details to restrict the search by. This
+    #   might include details like the format or locale of the template.
+    #
+    # ==== Returns
+    # Template:: A template object matching the name and details
+    def _find_by_parts(name, details)
+      # TODO: Make prefix actually part of details in ViewPath#find_by_parts
+      prefix = details.key?(:prefix) ? details.delete(:prefix) : "layouts"
+      view_paths.find_by_parts(name, details, prefix)
     end
 
-    def _default_layout(require_layout = false, details = {:formats => formats})
+    # Returns the default layout for this controller and a given set of details. 
+    # Optionally raises an exception if the layout could not be found.
+    #
+    # ==== Parameters
+    # details<Hash>:: A list of details to restrict the search by. This
+    #   might include details like the format or locale of the template.
+    # require_layout<Boolean>:: If this is true, raise an ArgumentError
+    #   with details about the fact that the exception could not be
+    #   found (defaults to false)
+    #
+    # ==== Returns
+    # Template:: The template object for the default layout (or nil)
+    def _default_layout(details, require_layout = false)
       if require_layout && _action_has_layout? && !_layout(details)
         raise ArgumentError,
           "There was no default layout for #{self.class} in #{view_paths.inspect}"
@@ -93,6 +143,12 @@ module AbstractController
       end
     end
 
+    # Determines whether the current action has a layout by checking the
+    # action name against the :only and :except conditions set on the
+    # layout.
+    #
+    # ==== Returns
+    # Boolean:: True if the action has a layout, false otherwise.
     def _action_has_layout?
       conditions = _layout_conditions
       if only = conditions[:only]
diff --git a/actionpack/lib/action_controller/abstract/logger.rb b/actionpack/lib/action_controller/abstract/logger.rb
index d6fa843485..b960e152e3 100644
--- a/actionpack/lib/action_controller/abstract/logger.rb
+++ b/actionpack/lib/action_controller/abstract/logger.rb
@@ -5,6 +5,13 @@ module AbstractController
   module Logger
     extend ActiveSupport::Concern
 
+    # A class that allows you to defer expensive processing
+    # until the logger actually tries to log. Otherwise, you are
+    # forced to do the processing in advance, and send the
+    # entire processed String to the logger, which might
+    # just discard the String if the log level is too low.
+    #
+    # TODO: Require that Rails loggers accept a block.
     class DelayedLog
       def initialize(&blk)
         @blk = blk
@@ -20,8 +27,10 @@ module AbstractController
       cattr_accessor :logger
     end
 
-    def process(action)
-      ret = super
+    # Override process_action in the AbstractController::Base
+    # to log details about the method.
+    def process_action(action)
+      super
 
       if logger
         log = DelayedLog.new do
@@ -32,10 +41,9 @@ module AbstractController
 
         logger.info(log)
       end
-
-      ret
     end
 
+  private
     def request_origin
       # this *needs* to be cached!
       # otherwise you'd get different results if calling it more than once
diff --git a/actionpack/lib/action_controller/abstract/renderer.rb b/actionpack/lib/action_controller/abstract/renderer.rb
index dd58c7cb64..611d3a16ce 100644
--- a/actionpack/lib/action_controller/abstract/renderer.rb
+++ b/actionpack/lib/action_controller/abstract/renderer.rb
@@ -14,10 +14,32 @@ module AbstractController
       self._view_paths ||= ActionView::PathSet.new
     end
 
+    # An instance of a view class. The default view class is ActionView::Base
+    #
+    # The view class must have the following methods:
+    # initialize[paths, assigns_for_first_render, controller]
+    #   paths<Array[ViewPath]>:: A list of resolvers to look for templates in
+    #   controller<AbstractController::Base> A controller
+    # _render_partial_from_controller[options]
+    #   options<Hash>:: see _render_partial in ActionView::Base
+    # _render_template_from_controller[template, layout, options, partial]
+    #   template<ActionView::Template>:: The template to render
+    #   layout<ActionView::Template>:: The layout to render around the template
+    #   options<Hash>:: See _render_template_with_layout in ActionView::Base
+    #   partial<Boolean>:: Whether or not the template to render is a partial
+    # _partial:: If a partial, rather than a template, was rendered, return
+    #   the partial.
+    # helpers:: A module containing the helpers to be used in the view. This
+    #   module should respond_to include.
+    # controller:: The controller that initialized the ActionView
+    #
+    # Override this method in a to change the default behavior.
     def _action_view
       @_action_view ||= ActionView::Base.new(self.class.view_paths, {}, self)
     end
 
+    # Mostly abstracts the fact that calling render twice is a DoubleRenderError.
+    # Delegates render_to_body and sticks the result in self.response_body.
     def render(*args)
       if response_body
         raise AbstractController::DoubleRenderError, "OMG"
@@ -27,9 +49,10 @@ module AbstractController
     end
 
     # Raw rendering of a template to a Rack-compatible body.
-    # ====
-    # @option _prefix<String> The template's path prefix
-    # @option _layout<String> The relative path to the layout template to use
+    #
+    # ==== Options
+    # _partial_object<Object>:: The object that is being rendered. If this
+    #   exists, we are in the special case of rendering an object as a partial.
     #
     # :api: plugin
     def render_to_body(options = {})
@@ -42,21 +65,27 @@ module AbstractController
       end
     end
 
-    # Raw rendering of a template to a string.
-    # ====
-    # @option _prefix<String> The template's path prefix
-    # @option _layout<String> The relative path to the layout template to use
+    # Raw rendering of a template to a string. Just convert the results of
+    # render_to_body into a String.
     #
     # :api: plugin
     def render_to_string(options = {})
       AbstractController::Renderer.body_to_s(render_to_body(options))
     end
 
+    # Renders the template from an object.
+    #
+    # ==== Options
+    # _template<ActionView::Template>:: The template to render
+    # _layout<ActionView::Template>:: The layout to wrap the template in (optional)
+    # _partial<TrueClass, FalseClass>:: Whether or not the template to be rendered is a partial
     def _render_template(options)
       _action_view._render_template_from_controller(options[:_template], options[:_layout], options, options[:_partial])
     end
 
-    def view_paths()
+    # The list of view paths for this controller. See ActionView::ViewPathSet for
+    # more details about writing custom view paths.
+    def view_paths
       _view_paths
     end
 
@@ -73,6 +102,15 @@ module AbstractController
     end
 
   private
+    # Take in a set of options and determine the template to render
+    #
+    # ==== Options
+    # _template<ActionView::Template>:: If this is provided, the search is over
+    # _template_name<#to_s>:: The name of the template to look up. Otherwise,
+    #   use the current action name.
+    # _prefix<String>:: The prefix to look inside of. In a file system, this corresponds
+    #   to a directory.
+    # _partial<TrueClass, FalseClass>:: Whether or not the file to look up is a partial
     def _determine_template(options)
       name = (options[:_template_name] || action_name).to_s
 
@@ -82,18 +120,36 @@ module AbstractController
     end
 
     module ClassMethods
+      # Append a path to the list of view paths for this controller.
+      #
+      # ==== Parameters
+      # path<String, ViewPath>:: If a String is provided, it gets converted into 
+      # the default view path. You may also provide a custom view path 
+      # (see ActionView::ViewPathSet for more information)
       def append_view_path(path)
         self.view_paths << path
       end
 
+      # Prepend a path to the list of view paths for this controller.
+      #
+      # ==== Parameters
+      # path<String, ViewPath>:: If a String is provided, it gets converted into 
+      # the default view path. You may also provide a custom view path 
+      # (see ActionView::ViewPathSet for more information)
       def prepend_view_path(path)
         self.view_paths.unshift(path)
       end
 
+      # A list of all of the default view paths for this controller.
       def view_paths
         self._view_paths
       end
 
+      # Set the view paths.
+      #
+      # ==== Parameters
+      # paths<ViewPathSet, Object>:: If a ViewPathSet is provided, use that;
+      #   otherwise, process the parameter into a ViewPathSet.
       def view_paths=(paths)
         self._view_paths = paths.is_a?(ActionView::PathSet) ?
                             paths : ActionView::Base.process_view_paths(paths)