Updated documentation

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

1 files changed, 29 insertions, 2 deletions

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