Updated documentation

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

6 files changed, 63 insertions, 29 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