Updated documentation

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

12 files changed, 80 insertions, 53 deletions

diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb
index 8bcf12a1a9..1eb32d2152 100755
--- a/actionpack/lib/action_controller/base.rb
+++ b/actionpack/lib/action_controller/base.rb
@@ -58,7 +58,7 @@ module ActionController #:nodoc:
   # accessing the environment hash, like this:
   #
   #   def hello_ip
-  #     location = @request.env["REMOTE_ADDRESS"]
+  #     location = @request.env["REMOTE_IP"]
   #     render_text "Hello stranger from #{location}"
   #   end
   #
diff --git a/actionpack/lib/action_controller/cookies.rb b/actionpack/lib/action_controller/cookies.rb
index 6b9954f84d..76ca12e913 100644
--- a/actionpack/lib/action_controller/cookies.rb
+++ b/actionpack/lib/action_controller/cookies.rb
@@ -10,15 +10,19 @@ module ActionController #:nodoc:
   #
   #   cookies["user_name"] # => "david"
   #   cookies.size         # => 2
+  # 
+  # Example for deleting:
+  #
+  #   cookies.delete "user_name"
   #
   # All the option symbols for setting cookies are:
   #
-  # value:: the cookie's value or list of values (as an array).
-  # path:: the path for which this cookie applies.  Defaults to the root of the application.
-  # domain:: the domain for which this cookie applies.
-  # expires:: the time at which this cookie expires, as a +Time+ object.
-  # secure:: whether this cookie is a secure cookie or not (default to false).
-  #          Secure cookies are only transmitted to HTTPS servers.
+  # * <tt>value</tt> - the cookie's value or list of values (as an array).
+  # * <tt>path</tt> - the path for which this cookie applies.  Defaults to the root of the application.
+  # * <tt>domain</tt> - the domain for which this cookie applies.
+  # * <tt>expires</tt> - the time at which this cookie expires, as a +Time+ object.
+  # * <tt>secure</tt> - whether this cookie is a secure cookie or not (default to false).
+  #   Secure cookies are only transmitted to HTTPS servers.
   module Cookies
     # Returns the cookie container, which operates as described above.
     def cookies
diff --git a/actionpack/lib/action_controller/dependencies.rb b/actionpack/lib/action_controller/dependencies.rb
index 6680d6cffd..d17369e5e1 100644
--- a/actionpack/lib/action_controller/dependencies.rb
+++ b/actionpack/lib/action_controller/dependencies.rb
@@ -20,33 +20,60 @@ module ActionController #:nodoc:
       base.extend(ClassMethods)
     end
 
+    # Dependencies control what classes are needed for the controller to run its course. This is an alternative to doing explicit
+    # +require+ statements that bring a number of benefits. It's more succinct, communicates what type of dependency we're talking about,
+    # can trigger special behavior (as in the case of +observer+), and enables Rails to be clever about reloading in cached environments
+    # like FCGI. Example:
+    #
+    #   class ApplicationController < ActionController::Base
+    #     model    :account, :company, :person, :project, :category
+    #     helper   :access_control
+    #     service  :notifications, :billings
+    #     observer :project_change_observer
+    #   end
+    #
+    # Please note that a controller like ApplicationController will automatically attempt to require_dependency on a model of its name and a helper
+    # of its name. If nothing is found, no error is raised. This is especially useful for concrete controllers like PostController:
+    #
+    #   class PostController < ApplicationController
+    #     # model  :post (already required)
+    #     # helper :post (already required)
+    #   end
     module ClassMethods
       # Loads the <tt>file_name</tt> if reload_dependencies is true or requires if it's false.
       def require_dependency(file_name)
         reload_dependencies ? silence_warnings { load("#{file_name}.rb") } : require(file_name)
       end
       
+      # Specifies a variable number of models that this controller depends on. Models are normally Active Record classes or a similar
+      # backend for modelling entity classes.
       def model(*models)
         require_dependencies(:model, models)
         depend_on(:model, models)
       end
 
+      # Specifies a variable number of services that this controller depends on. Services are normally singletons or factories, like
+      # Action Mailer service or a Payment Gateway service.
       def service(*services)
         require_dependencies(:service, services)
         depend_on(:service, services)
       end
       
+      # Specifies a variable number of observers that are to govern when this controller is handling actions. The observers will
+      # automatically have .instance called on them to make them active on assignment.
       def observer(*observers)
         require_dependencies(:observer, observers)
         depend_on(:observer, observers)
         instantiate_observers(observers)
       end
 
-      def dependencies_on(layer) # :nodoc:
+      # Returns an array of symbols that specify the dependencies on a given layer. For the example at the top, calling
+      # <tt>ApplicationController.dependencies_on(:model)</tt> would return <tt>[:account, :company, :person, :project, :category]</tt>
+      def dependencies_on(layer)
         read_inheritable_attribute("#{layer}_dependencies")
       end
     
-      def depend_on(layer, dependencies)
+      def depend_on(layer, dependencies) #:nodoc:
         write_inheritable_array("#{layer}_dependencies", dependencies)
       end
 
diff --git a/actionpack/lib/action_controller/helpers.rb b/actionpack/lib/action_controller/helpers.rb
index 3def790cc6..06bbd56283 100644
--- a/actionpack/lib/action_controller/helpers.rb
+++ b/actionpack/lib/action_controller/helpers.rb
@@ -31,7 +31,7 @@ module ActionController #:nodoc:
       # 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(helper_module)
+      def add_template_helper(helper_module) #:nodoc:
         template_class.class_eval "include #{helper_module}"
       end
 
diff --git a/actionpack/lib/action_controller/rescue.rb b/actionpack/lib/action_controller/rescue.rb
index e1ba86be6e..9d7c3d95b2 100644
--- a/actionpack/lib/action_controller/rescue.rb
+++ b/actionpack/lib/action_controller/rescue.rb
@@ -15,7 +15,7 @@ module ActionController #:nodoc:
       end
     end
 
-    module ClassMethods
+    module ClassMethods #:nodoc:
       def process_with_exception(request, response, exception)
         new.process(request, response, :rescue_action, exception)
       end
diff --git a/actionpack/lib/action_controller/test_process.rb b/actionpack/lib/action_controller/test_process.rb
index 314f087f6f..3590d29cd3 100644
--- a/actionpack/lib/action_controller/test_process.rb
+++ b/actionpack/lib/action_controller/test_process.rb
@@ -187,25 +187,28 @@ end
   end
 end
 
-class Test::Unit::TestCase #:nodoc:
-  private  
-    # execute the request and set/volley the response
-    def process(action, parameters = nil, session = nil)
-      @request.env['REQUEST_METHOD'] ||= "GET"
-      @request.action = action.to_s
-      @request.parameters.update(parameters) unless parameters.nil?
-      @request.session = ActionController::TestSession.new(session) unless session.nil?
-      @controller.process(@request, @response)
-    end
+module Test
+  module Unit
+    class TestCase #:nodoc:
+      private  
+        # execute the request and set/volley the response
+        def process(action, parameters = nil, session = nil)
+          @request.env['REQUEST_METHOD'] ||= "GET"
+          @request.action = action.to_s
+          @request.parameters.update(parameters) unless parameters.nil?
+          @request.session = ActionController::TestSession.new(session) unless session.nil?
+          @controller.process(@request, @response)
+        end
     
-    # execute the request simulating a specific http method and set/volley the response
-    %w( get post put delete head ).each do |method|
-      class_eval <<-EOV
-        def #{method}(action, parameters = nil, session = nil)
-          @request.env['REQUEST_METHOD'] = "#{method.upcase}"
-          process(action, parameters, session)
+        # execute the request simulating a specific http method and set/volley the response
+        %w( get post put delete head ).each do |method|
+          class_eval <<-EOV
+            def #{method}(action, parameters = nil, session = nil)
+              @request.env['REQUEST_METHOD'] = "#{method.upcase}"
+              process(action, parameters, session)
+            end
+          EOV
         end
-      EOV
     end
-
+  end
 end
\ No newline at end of file
diff --git a/actionpack/lib/action_view.rb b/actionpack/lib/action_view.rb
index c39765d436..4caf9d8236 100644
--- a/actionpack/lib/action_view.rb
+++ b/actionpack/lib/action_view.rb
@@ -28,15 +28,6 @@ rescue LoadError
   # RubyGems is not available, use included Builder
   $:.unshift(File.dirname(__FILE__) + "/action_view/vendor")
   require 'action_view/vendor/builder'
-ensure
-  # Temporary patch until it's in Builder 1.2.2
-  class BlankSlate
-    class << self
-      def hide(name)
-        undef_method name if instance_methods.include?(name) and name !~ /^(__|instance_eval)/
-      end
-    end
-  end
 end
 
 require 'action_view/base'
diff --git a/actionpack/lib/action_view/base.rb b/actionpack/lib/action_view/base.rb
index 24c33cd11d..ad809e2bff 100644
--- a/actionpack/lib/action_view/base.rb
+++ b/actionpack/lib/action_view/base.rb
@@ -141,7 +141,7 @@ module ActionView #:nodoc:
       end
     end
 
-    def self.controller_delegate(*methods)
+    def self.controller_delegate(*methods)#:nodoc:
       methods.flatten.each do |method|
         class_eval <<-end_eval
           def #{method}(*args, &block)
diff --git a/actionpack/lib/action_view/helpers/active_record_helper.rb b/actionpack/lib/action_view/helpers/active_record_helper.rb
index a2b5a8b004..07ede179e6 100644
--- a/actionpack/lib/action_view/helpers/active_record_helper.rb
+++ b/actionpack/lib/action_view/helpers/active_record_helper.rb
@@ -83,9 +83,9 @@ module ActionView
       # Returns a string with a div containing all the error messages for the object located as an instance variable by the name
       # of <tt>object_name</tt>. This div can be tailored by the following options:
       #
-      # ::header_tag: Used for the header of the error div (default: h2)
-      # ::id: The id of the error div (default: errorExplanation)
-      # ::class: The class of the error div (default: errorExplanation)
+      # * <tt>header_tag</tt> - Used for the header of the error div (default: h2)
+      # * <tt>id</tt> - The id of the error div (default: errorExplanation)
+      # * <tt>class</tt> - The class of the error div (default: errorExplanation)
       def error_messages_for(object_name, options={})
         object = instance_eval "@#{object_name}"
         unless object.errors.empty?
diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 0a406cfc47..253b389a79 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -91,11 +91,13 @@ module ActionView
       #
       # Example (call, result). Imagine that @post.validated? returns 1:
       #   check_box("post", "validated")
-      #     <input type="checkbox" id="post_validate" name="post[validated] value="1" checked="checked" /><input name="post[validated]" type="hidden" value="0" />
+      #     <input type="checkbox" id="post_validate" name="post[validated] value="1" checked="checked" />
+      #     <input name="post[validated]" type="hidden" value="0" />
       #
       # Example (call, result). Imagine that @puppy.gooddog returns no:
       #   check_box("puppy", "gooddog", {}, "yes", "no")
-      #     <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog] value="yes" /><input name="puppy[gooddog]" type="hidden" value="no" />
+      #     <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog] value="yes" />
+      #     <input name="puppy[gooddog]" type="hidden" value="no" />
       def check_box(object, method, options = {}, checked_value = "1", unchecked_value = "0")
         InstanceTag.new(object, method, self).to_check_box_tag(options, checked_value, unchecked_value)
       end
diff --git a/actionpack/lib/action_view/helpers/tag_helper.rb b/actionpack/lib/action_view/helpers/tag_helper.rb
index 6139943567..bf81d5d909 100644
--- a/actionpack/lib/action_view/helpers/tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/tag_helper.rb
@@ -7,16 +7,16 @@ module ActionView
       include ERB::Util
 
       # Examples: 
-      # * tag("br") => <br />
-      # * tag("input", { "type" => "text"}) => <input type="text" />
+      # * <tt>tag("br") => <br /></tt>
+      # * <tt>tag("input", { "type" => "text"}) => <input type="text" /></tt>
       def tag(name, options = {}, open = false)
         "<#{name}#{tag_options(options)}" + (open ? ">" : " />")
       end
       
       # Examples: 
-      # * content_tag("p", "Hello world!") => <p>Hello world!</p>
-      # * content_tag("div", content_tag("p", "Hello world!"), "class" => "strong") => 
-      #   <div class="strong"><p>Hello world!</p></div>
+      # * <tt>content_tag("p", "Hello world!") => <p>Hello world!</p></tt>
+      # * <tt>content_tag("div", content_tag("p", "Hello world!"), "class" => "strong") => </tt>
+      #   <tt><div class="strong"><p>Hello world!</p></div></tt>
       def content_tag(name, content, options = {})
         "<#{name}#{tag_options(options)}>#{content}</#{name}>"
       end
diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index f0eed442cf..127c7a42d5 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -30,10 +30,10 @@ module ActionView
       # get a link tag that just points without consideration. The <tt>html_options</tt> works jointly for the image and ahref tag by
       # letting the following special values enter the options on the image and the rest goes to the ahref:
       #
-      # ::alt: If no alt text is given, the file name part of the +src+ is used (capitalized and without the extension)
-      # ::size: Supplied as "XxY", so "30x45" becomes width="30" and height="45"
-      # ::border: Is set to 0 by default
-      # ::align: Sets the alignment, no special features
+      # * <tt>alt</tt> - If no alt text is given, the file name part of the +src+ is used (capitalized and without the extension)
+      # * <tt>size</tt> - Supplied as "XxY", so "30x45" becomes width="30" and height="45"
+      # * <tt>border</tt> - Is set to 0 by default
+      # * <tt>align</tt> - Sets the alignment, no special features
       #
       # The +src+ can be supplied as a... 
       # * full path, like "/my_images/image.gif"