Update/clean up AP documentation (rdoc)

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

11 files changed, 45 insertions, 34 deletions

diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG
index 1fe52f40fa..173dbdde30 100644
--- a/actionpack/CHANGELOG
+++ b/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]
diff --git a/actionpack/README b/actionpack/README
index 1a2da631b1..c8624bf407 100755
--- a/actionpack/README
+++ b/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,7 +370,7 @@ methods:
     end
     
     def display
-      @post = Post.find(@params["id"])
+      @post = Post.find(:params[:id])
     end
     
     def new
@@ -378,7 +378,7 @@ methods:
     end
     
     def create
-      @post = Post.create(@params["post"])
+      @post = Post.create(params[:post])
       redirect_to :action => "display", :id => @post.id
     end
   end
diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb
index 6b9456cf1f..4cb8c11588 100755
--- a/actionpack/lib/action_controller/base.rb
+++ b/actionpack/lib/action_controller/base.rb
@@ -46,7 +46,7 @@ module ActionController #:nodoc:
   #     end
   #     
   #     def sign
-  #       Entry.create(@params["entry"])
+  #       Entry.create(params[:entry])
   #       redirect_to :action => "index"
   #     end
   #   end
@@ -83,7 +83,7 @@ module ActionController #:nodoc:
   #
   #   def hello_ip
   #     location = request.env["REMOTE_IP"]
-  #     render_text "Hello stranger from #{location}"
+  #     render :text => "Hello stranger from #{location}"
   #   end
   #
   # == Parameters
diff --git a/actionpack/lib/action_controller/caching.rb b/actionpack/lib/action_controller/caching.rb
index 2a9c388250..4c71632c4b 100644
--- a/actionpack/lib/action_controller/caching.rb
+++ b/actionpack/lib/action_controller/caching.rb
@@ -350,7 +350,7 @@ module ActionController #:nodoc:
         end
       end
 
-      module ThreadSafety
+      module ThreadSafety #:nodoc:
         def read(name, options=nil) #:nodoc:
           @mutex.synchronize { super }
         end
diff --git a/actionpack/lib/action_controller/flash.rb b/actionpack/lib/action_controller/flash.rb
index 90c464dd81..674f73f1a4 100644
--- a/actionpack/lib/action_controller/flash.rb
+++ b/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 @@ module ActionController #: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,7 +82,7 @@ module ActionController #:nodoc:
       # 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
@@ -90,7 +90,7 @@ module ActionController #:nodoc:
       # 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
diff --git a/actionpack/lib/action_controller/pagination.rb b/actionpack/lib/action_controller/pagination.rb
index 709b56bfba..9a3584bfab 100644
--- a/actionpack/lib/action_controller/pagination.rb
+++ b/actionpack/lib/action_controller/pagination.rb
@@ -167,7 +167,7 @@ module ActionController
     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],
diff --git a/actionpack/lib/action_controller/request.rb b/actionpack/lib/action_controller/request.rb
index aace415943..a61788237c 100755
--- a/actionpack/lib/action_controller/request.rb
+++ b/actionpack/lib/action_controller/request.rb
@@ -130,6 +130,8 @@ module ActionController
       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 @@ module ActionController
     #--
     # 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
diff --git a/actionpack/lib/action_controller/session_management.rb b/actionpack/lib/action_controller/session_management.rb
index 6752d66e85..0da594d638 100644
--- a/actionpack/lib/action_controller/session_management.rb
+++ b/actionpack/lib/action_controller/session_management.rb
@@ -77,7 +77,7 @@ module ActionController #:nodoc:
         write_inheritable_array("session_options", [options])
       end
 
-      def cached_session_options
+      def cached_session_options #:nodoc:
         @session_options ||= read_inheritable_attribute("session_options") || []
       end
 
diff --git a/actionpack/lib/action_pack/version.rb b/actionpack/lib/action_pack/version.rb
index 76949610f0..3242498d35 100644
--- a/actionpack/lib/action_pack/version.rb
+++ b/actionpack/lib/action_pack/version.rb
@@ -1,5 +1,5 @@
 module ActionPack
-  module Version
+  module Version #:nodoc:
     MAJOR = 1
     MINOR = 9
     TINY  = 1
diff --git a/actionpack/lib/action_view/base.rb b/actionpack/lib/action_view/base.rb
index f9b35260bd..4c065a0ae5 100644
--- a/actionpack/lib/action_view/base.rb
+++ b/actionpack/lib/action_view/base.rb
@@ -135,7 +135,7 @@ module ActionView #:nodoc:
 
     @@template_handlers = {}
  
-    module CompiledTemplates
+    module CompiledTemplates #:nodoc:
       # holds compiled template code
     end
     include CompiledTemplates
@@ -162,6 +162,13 @@ module ActionView #: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
diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb
index 74f7337289..4ead8a816f 100644
--- a/actionpack/lib/action_view/helpers/text_helper.rb
+++ b/actionpack/lib/action_view/helpers/text_helper.rb
@@ -252,7 +252,7 @@ module ActionView
         cycle.reset
       end
 
-      class Cycle
+      class Cycle #:nodoc:
         attr_reader :values
         
         def initialize(first_value, *values)