Adding documentation to actionview so that the big picture of the

renderer is clearer.

4 files changed, 41 insertions, 0 deletions

diff --git a/actionpack/lib/action_view/path_set.rb b/actionpack/lib/action_view/path_set.rb
index d9c76366f8..91ee2ea8f5 100644
--- a/actionpack/lib/action_view/path_set.rb
+++ b/actionpack/lib/action_view/path_set.rb
@@ -1,5 +1,11 @@
 module ActionView #:nodoc:
   # = Action View PathSet
+  #
+  # This class is used to store and access paths in Action View. A number of
+  # operations are defined so that you can search among the paths in this
+  # set and also perform operations on other +PathSet+ objects.
+  #
+  # A +LookupContext+ will use a +PathSet+ to store the paths in its context.
   class PathSet #:nodoc:
     include Enumerable
 
diff --git a/actionpack/lib/action_view/renderer/abstract_renderer.rb b/actionpack/lib/action_view/renderer/abstract_renderer.rb
index 6fb8cbb46c..73c19a0ae2 100644
--- a/actionpack/lib/action_view/renderer/abstract_renderer.rb
+++ b/actionpack/lib/action_view/renderer/abstract_renderer.rb
@@ -1,4 +1,19 @@
 module ActionView
+  # This class defines the interface for a renderer. Each class that
+  # subclasses +AbstractRenderer+ is used by the base +Renderer+ class to
+  # render a specific type of object.
+  #
+  # The base +Renderer+ class uses its +render+ method to delegate to the
+  # renderers. These currently consist of
+  #
+  #   PartialRenderer - Used for rendering partials
+  #   TemplateRenderer - Used for rendering other types of templates
+  #   StreamingTemplateRenderer - Used for streaming
+  #
+  # Whenever the +render+ method is called on the base +Renderer+ class, a new
+  # renderer object of the correct type is created, and the +render+ method on
+  # that new object is called in turn. This abstracts the setup and rendering
+  # into a separate classes for partials and templates.
   class AbstractRenderer #:nodoc:
     delegate :find_template, :template_exists?, :with_fallbacks, :with_layout_format, :formats, :to => :@lookup_context
 
diff --git a/actionpack/lib/action_view/renderer/partial_renderer.rb b/actionpack/lib/action_view/renderer/partial_renderer.rb
index 43a88b0623..821026268a 100644
--- a/actionpack/lib/action_view/renderer/partial_renderer.rb
+++ b/actionpack/lib/action_view/renderer/partial_renderer.rb
@@ -313,6 +313,13 @@ module ActionView
 
     private
 
+    # Sets up instance variables needed for rendering a partial. This method
+    # finds the options and details and extracts them. The method also contains
+    # logic that handles the type of object passed in as the partial.
+    #
+    # If +options[:partial]+ is a string, then the +@path+ instance variable is
+    # set to that string. Otherwise, the +options[:partial]+ object must
+    # respond to +to_partial_path+ in order to setup the path.
     def setup(context, options, block)
       @view   = context
       partial = options[:partial]
@@ -413,6 +420,13 @@ module ActionView
       end
     end
 
+    # Obtains the path to where the object's partial is located. If the object
+    # responds to +to_partial_path+, then +to_partial_path+ will be called and
+    # will provide the path. If the object does not respond to +to_partial_path+,
+    # then an +ArgumentError+ is raised.
+    #
+    # If +prefix_partial_path_with_controller_namespace+ is true, then this
+    # method will prefix the partial paths with a namespace.
     def partial_path(object = @object)
       object = object.to_model if object.respond_to?(:to_model)
 
diff --git a/actionpack/lib/action_view/renderer/renderer.rb b/actionpack/lib/action_view/renderer/renderer.rb
index 30a0c4be70..964b18337e 100644
--- a/actionpack/lib/action_view/renderer/renderer.rb
+++ b/actionpack/lib/action_view/renderer/renderer.rb
@@ -2,6 +2,12 @@ module ActionView
   # This is the main entry point for rendering. It basically delegates
   # to other objects like TemplateRenderer and PartialRenderer which
   # actually renders the template.
+  #
+  # The Renderer will parse the options from the +render+ or +render_body+
+  # method and render a partial or a template based on the options. The
+  # +TemplateRenderer+ and +PartialRenderer+ objects are wrappers which do all
+  # the setup and logic necessary to render a view and a new object is created
+  # each time +render+ is called.
   class Renderer
     attr_accessor :lookup_context