Update/clean up AP documentation (rdoc)

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

actionpack/CHANGELOG

@@ -1,5 +1,7 @@
 *SVN*
 
+* Update/clean up documentation (rdoc)
+
 * Upgrade to Prototype 1.4.0_rc0 [Sam Stephenson]
 
 * Added assert_vaild. Reports the proper AR error messages as fail message when the passed record is invalid [Tobias Luetke]

actionpack/README

@@ -40,14 +40,14 @@ A short rundown of the major features:
 
       def update
         @customer = find_customer
-        @customer.attributes = @params["customer"]
+        @customer.attributes = params[:customer]
         @customer.save ? 
           redirect_to(:action => "display") : 
           render(:action => "edit")
       end
 
       private
-        def find_customer() Customer.find(@params["id"]) end
+        def find_customer() Customer.find(params[:id]) end
     end
 
   {Learn more}[link:classes/ActionController/Base.html]
@@ -182,7 +182,7 @@ A short rundown of the major features:
     # controller
     def list
       @pages, @people =
-        paginate :people, :order_by => 'last_name, first_name'
+        paginate :people, :order => 'last_name, first_name'
     end
 
     # view
@@ -202,8 +202,8 @@ A short rundown of the major features:
       end
 
       def test_failing_authenticate
-        process :authenticate, "user_name" => "nop", "password" => ""
-        assert_flash_has 'alert'
+        process :authenticate, :user_name => "nop", :password => ""
+        assert flash.has_key?(:alert)
         assert_redirected_to :action => "index"
       end
     end
@@ -252,10 +252,10 @@ A short rundown of the major features:
       end
 
       def update
-        List.update(@params["list"]["id"], @params["list"])
-        expire_page   :action => "show", :id => @params["list"]["id"]
+        List.update(params[:list][:id], params[:list])
+        expire_page   :action => "show", :id => params[:list][:id]
         expire_action :action => "account"
-        redirect_to   :action => "show", :id => @params["list"]["id"]
+        redirect_to   :action => "show", :id => params[:list][:id]
       end
     end
 
@@ -342,8 +342,8 @@ A short rundown of the major features:
 
     class WeblogController < ActionController::Base
       def save
-        post = Post.create(@params["post"])
-        redirect_to :action => "display", :path_params => { "id" => post.id }
+        post = Post.create(params[:post])
+        redirect_to :action => "display", :id => post.id
       end
     end
 
@@ -370,15 +370,15 @@ methods:
     end
 
     def display
-      @post = Post.find(@params["id"])
+      @post = Post.find(:params[:id])
     end
 
     def new
       @post = Post.new
     end
 
     def create
-      @post = Post.create(@params["post"])
+      @post = Post.create(params[:post])
       redirect_to :action => "display", :id => @post.id
     end
   end

actionpack/lib/action_controller/base.rb

@@ -46,7 +46,7 @@ def initialize(message=nil)
   #     end
   #     
   #     def sign
-  #       Entry.create(@params["entry"])
+  #       Entry.create(params[:entry])
   #       redirect_to :action => "index"
   #     end
   #   end
@@ -83,7 +83,7 @@ def initialize(message=nil)
   #
   #   def hello_ip
   #     location = request.env["REMOTE_IP"]
-  #     render_text "Hello stranger from #{location}"
+  #     render :text => "Hello stranger from #{location}"
   #   end
   #
   # == Parameters

actionpack/lib/action_controller/caching.rb

@@ -350,7 +350,7 @@ def delete_matched(matcher, options=nil) #:nodoc:
         end
       end
 
-      module ThreadSafety
+      module ThreadSafety #:nodoc:
         def read(name, options=nil) #:nodoc:
           @mutex.synchronize { super }
         end

actionpack/lib/action_controller/flash.rb

@@ -1,14 +1,14 @@
 module ActionController #:nodoc:
   # The flash provides a way to pass temporary objects between actions. Anything you place in the flash will be exposed
   # to the very next action and then cleared out. This is a great way of doing notices and alerts, such as a create action
-  # that sets <tt>flash["notice"] = "Successfully created"</tt> before redirecting to a display action that can then expose 
+  # that sets <tt>flash[:notice] = "Successfully created"</tt> before redirecting to a display action that can then expose 
   # the flash to its template. Actually, that exposure is automatically done. Example:
   #
   #   class WeblogController < ActionController::Base
   #     def create
   #       # save post
-  #       flash["notice"] = "Successfully created post"
-  #       redirect_to :action => "display", :params => { "id" => post.id }
+  #       flash[:notice] = "Successfully created post"
+  #       redirect_to :action => "display", :params => { :id => post.id }
   #     end
   #
   #     def display
@@ -17,7 +17,7 @@ module ActionController #:nodoc:
   #   end
   #
   #   display.rhtml
-  #     <% if @flash["notice"] %><div class="notice"><%= @flash["notice"] %></div><% end %>
+  #     <% if @flash[:notice] %><div class="notice"><%= @flash[:notice] %></div><% end %>
   #
   # This example just places a string in the flash, but you can put any object in there. And of course, you can put as many
   # as you like at a time too. Just remember: They'll be gone by the time the next action has been performed.
@@ -67,7 +67,7 @@ def replace h #:nodoc:
 
       # Sets a flash that will not be available to the next action, only to the current.
       #
-      #     flash.now["message"] = "Hello current action"
+      #     flash.now[:message] = "Hello current action"
       # 
       # This method enables you to use the flash as a central messaging system in your app.
       # When you need to pass an object to the next action, you use the standard flash assign (<tt>[]=</tt>).
@@ -82,15 +82,15 @@ def now
       # Keeps either the entire current flash or a specific flash entry available for the next action:
       #
       #    flash.keep            # keeps the entire flash
-      #    flash.keep("notice")  # keeps only the "notice" entry, the rest of the flash is discarded
+      #    flash.keep(:notice)   # keeps only the "notice" entry, the rest of the flash is discarded
       def keep(k=nil)
         use(k, false)
       end
 
       # Marks the entire flash or a single flash entry to be discarded by the end of the current action
       #
       #     flash.keep                 # keep entire flash available for the next action
-      #     flash.discard('warning')   # discard the "warning" entry (it'll still be available for the current action)
+      #     flash.discard(:warning)    # discard the "warning" entry (it'll still be available for the current action)
       def discard(k=nil)
         use(k)
       end

actionpack/lib/action_controller/pagination.rb

@@ -167,7 +167,7 @@ def count_collection_for_pagination(model, conditions, joins)
     end
 
     # Returns a collection of items for the given +model+ and +options[conditions]+,
-    # ordered by +options[order_by]+, for the current page in the given +paginator+.
+    # ordered by +options[order]+, for the current page in the given +paginator+.
     # Override this method to implement a custom finder.
     def find_collection_for_pagination(model, options, paginator)
       model.find(:all, :conditions => options[:conditions],

actionpack/lib/action_controller/request.rb

@@ -130,6 +130,8 @@ def raw_post
       env['RAW_POST_DATA']
     end
 
+    # Returns the request URI correctly, taking into account the idiosyncracies
+    # of the various servers.
     def request_uri
       if uri = env['REQUEST_URI']
         (%r{^\w+\://[^/]+(/.*|$)$} =~ uri) ? $1 : uri # Remove domain, which webrick puts into the request_uri.
@@ -216,25 +218,25 @@ def server_software
     #--
     # Must be implemented in the concrete request
     #++
-    def query_parameters
+    def query_parameters #:nodoc:
     end
 
-    def request_parameters
+    def request_parameters #:nodoc:
     end
 
-    def env
+    def env #:nodoc:
     end
 
-    def host
+    def host #:nodoc:
     end
 
-    def cookies
+    def cookies #:nodoc:
     end
 
-    def session
+    def session #:nodoc:
     end
 
-    def reset_session
+    def reset_session #:nodoc:
     end    
   end
 end

actionpack/lib/action_controller/session_management.rb

@@ -77,7 +77,7 @@ def session(*args)
         write_inheritable_array("session_options", [options])
       end
 
-      def cached_session_options
+      def cached_session_options #:nodoc:
         @session_options ||= read_inheritable_attribute("session_options") || []
       end
 

actionpack/lib/action_pack/version.rb

@@ -1,5 +1,5 @@
 module ActionPack
-  module Version
+  module Version #:nodoc:
     MAJOR = 1
     MINOR = 9
     TINY  = 1

actionpack/lib/action_view/base.rb

@@ -135,7 +135,7 @@ class Base
 
     @@template_handlers = {}
 
-    module CompiledTemplates
+    module CompiledTemplates #:nodoc:
       # holds compiled template code
     end
     include CompiledTemplates
@@ -162,6 +162,13 @@ def self.load_helpers(helper_dir)#:nodoc:
       end
     end
 
+    # Register a class that knows how to handle template files with the given
+    # extension. This can be used to implement new template types.
+    # The constructor for the class must take the ActiveView::Base instance
+    # as a parameter, and the class must implement a #render method that
+    # takes the contents of the template to render as well as the Hash of
+    # local assigns available to the template. The #render method ought to
+    # return the rendered template as a string.
     def self.register_template_handler(extension, klass)
       @@template_handlers[extension] = klass
     end

actionpack/lib/action_view/helpers/text_helper.rb

@@ -252,7 +252,7 @@ def reset_cycle(name = "default")
         cycle.reset
       end
 
-      class Cycle
+      class Cycle #:nodoc:
         attr_reader :values
 
         def initialize(first_value, *values)