Made documentation ready for release (AP)

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

9 files changed, 71 insertions, 57 deletions

diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG
index 1b973abf9d..4e6ebdb5be 100644
--- a/actionpack/CHANGELOG
+++ b/actionpack/CHANGELOG
@@ -1,7 +1,5 @@
 *1.9.0* (6 July, 2005)
 
-* Fixed that a SessionRestoreError was thrown if a model object was placed in the session that wasn't available to all controllers
-
 * Added logging of the request URI in the benchmark statement (makes it easy to grep for slow actions)
 
 * Added javascript_include_tag :defaults shortcut that'll include all the default javascripts included with Action Pack (prototype, effects, controls, dragdrop)
diff --git a/actionpack/lib/action_controller/caching.rb b/actionpack/lib/action_controller/caching.rb
index 28c702e60f..20a4d7aba1 100644
--- a/actionpack/lib/action_controller/caching.rb
+++ b/actionpack/lib/action_controller/caching.rb
@@ -458,7 +458,7 @@ module ActionController #:nodoc:
     end
     
     if defined?(ActiveRecord::Observer)
-      class Sweeper < ActiveRecord::Observer
+      class Sweeper < ActiveRecord::Observer #:nodoc:
         attr_accessor :controller
         
         def before(controller)
diff --git a/actionpack/lib/action_controller/code_generation.rb b/actionpack/lib/action_controller/code_generation.rb
index a480003720..6762b7610d 100644
--- a/actionpack/lib/action_controller/code_generation.rb
+++ b/actionpack/lib/action_controller/code_generation.rb
@@ -1,9 +1,9 @@
 module ActionController
-  module CodeGeneration #:nodoc
-    class GenerationError < StandardError
+  module CodeGeneration #:nodoc:
+    class GenerationError < StandardError #:nodoc:
     end
   
-    class Source
+    class Source #:nodoc:
       attr_reader :lines, :indentation_level
       IndentationString = '  '
       def initialize
@@ -24,7 +24,7 @@ module ActionController
       def to_s() lines.join("\n") end
     end
 
-    class CodeGenerator
+    class CodeGenerator #:nodoc:
       attr_accessor :source, :locals
       def initialize(source = nil)
         @locals = []
@@ -72,7 +72,7 @@ module ActionController
       end
     end
 
-    class RecognitionGenerator < CodeGenerator
+    class RecognitionGenerator < CodeGenerator #:nodoc:
       Attributes = [:after, :before, :current, :results, :constants, :depth, :move_ahead, :finish_statement]
       attr_accessor(*Attributes)
       FieldsToDuplicate = CodeGenerator::FieldsToDuplicate + Attributes
@@ -163,7 +163,7 @@ module ActionController
       end
     end
   
-    class GenerationGenerator < CodeGenerator
+    class GenerationGenerator < CodeGenerator #:nodoc:
       Attributes = [:after, :before, :current, :segments]
       attr_accessor(*Attributes)
       FieldsToDuplicate = CodeGenerator::FieldsToDuplicate + Attributes
diff --git a/actionpack/lib/action_controller/layout.rb b/actionpack/lib/action_controller/layout.rb
index 07c02f0de3..d7e01564a0 100644
--- a/actionpack/lib/action_controller/layout.rb
+++ b/actionpack/lib/action_controller/layout.rb
@@ -125,7 +125,7 @@ module ActionController #:nodoc:
     #
     # If you have a layout that by default is applied to all the actions of a controller, you still have the option of rendering
     # a given action or set of actions without a layout, or restricting a layout to only a single action or a set of actions. The 
-    # +:only+ and +:except+ options can be passed to the layout call. For example:
+    # <tt>:only</tt> and <tt>:except</tt> options can be passed to the layout call. For example:
     #
     #   class WeblogController < ActionController::Base
     #     layout "weblog_standard", :except => :rss
@@ -137,8 +137,8 @@ module ActionController #:nodoc:
     # This will assign "weblog_standard" as the WeblogController's layout  except for the +rss+ action, which will not wrap a layout 
     # around the rendered view.
     #
-    # Both the +:only+ and +:except+ condition can accept an arbitrary number of method references, so +:except => [ :rss, :text_only ]+ 
-    # is valid, as is # +:except => :rss+.
+    # Both the <tt>:only</tt> and <tt>:except</tt> condition can accept an arbitrary number of method references, so 
+    # #<tt>:except => [ :rss, :text_only ]</tt> is valid, as is <tt>:except => :rss</tt>.
     #
     # == Using a different layout in the action render call
     # 
diff --git a/actionpack/lib/action_controller/routing.rb b/actionpack/lib/action_controller/routing.rb
index f8ca5e0930..d2e719bf40 100644
--- a/actionpack/lib/action_controller/routing.rb
+++ b/actionpack/lib/action_controller/routing.rb
@@ -1,7 +1,6 @@
 module ActionController
-  module Routing
+  module Routing #:nodoc:
     class << self
-
       def expiry_hash(options, recall)
         k = v = nil
         expire_on = {}
@@ -44,7 +43,7 @@ module ActionController
       end
     end
 
-    class Component #:nodoc
+    class Component #:nodoc:
       def dynamic?()  false end
       def optional?() false end
 
@@ -61,7 +60,7 @@ module ActionController
       end 
     end
 
-    class StaticComponent < Component #:nodoc
+    class StaticComponent < Component #:nodoc:
       attr_reader :value
   
       def initialize(value)
@@ -79,7 +78,7 @@ module ActionController
       end
     end
 
-    class DynamicComponent < Component #:nodoc
+    class DynamicComponent < Component #:nodoc:
       attr_reader :key, :default
       attr_accessor :condition
   
@@ -174,7 +173,7 @@ module ActionController
       end
     end
 
-    class ControllerComponent < DynamicComponent #:nodoc
+    class ControllerComponent < DynamicComponent #:nodoc:
       def key() :controller end
 
       def add_segments_to(g)
@@ -225,7 +224,7 @@ module ActionController
       end
     end
 
-    class PathComponent < DynamicComponent #:nodoc 
+    class PathComponent < DynamicComponent #:nodoc:
       def optional?() true end
       def default()   ''   end
       def condition() nil  end
@@ -255,7 +254,7 @@ module ActionController
       end
     end
 
-    class Route
+    class Route #:nodoc:
       attr_accessor :components, :known
       attr_reader :path, :options, :keys
   
@@ -351,7 +350,7 @@ module ActionController
         end
     end
 
-    class RouteSet
+    class RouteSet #:nodoc:
       attr_reader :routes, :categories, :controller_to_selector
       def initialize
         @routes = []
@@ -563,7 +562,7 @@ module ActionController
       end
     end
 
-    module NamedRoutes
+    module NamedRoutes #:nodoc:
       Helpers = []
       class << self
         def clear() Helpers.clear end
diff --git a/actionpack/lib/action_controller/upload_progress.rb b/actionpack/lib/action_controller/upload_progress.rb
index 1e45f9daf2..6ffe429758 100644
--- a/actionpack/lib/action_controller/upload_progress.rb
+++ b/actionpack/lib/action_controller/upload_progress.rb
@@ -6,6 +6,13 @@
 require 'action_controller/cgi_ext/multipart_progress'
 
 module ActionController #:nodoc:
+  # == THIS IS AN EXPERIMENTAL FEATURE
+  #
+  # Which means that it doesn't yet work on all systems. We're still working on full
+  # compatibility. It's thus not advised to use this unless you've verified it to work
+  # fully on all the systems that is a part of your environment. Consider this an extended
+  # preview.
+  #
   # == Action Pack Upload Progress for multipart uploads
   #
   # The UploadProgress module aids in the process of viewing an Ajax driven
@@ -124,9 +131,7 @@ module ActionController #:nodoc:
   #   def custom_status
   #     render :inline => '<%= upload_progress_status %> <div>Updated at <%= Time.now %></div>', :layout => false
   #   end
-  #
-  #
-  module UploadProgress #:nodoc:
+  module UploadProgress
     def self.append_features(base) #:nodoc:
       super
       base.extend(ClassMethods)
@@ -262,6 +267,13 @@ module ActionController #:nodoc:
       session[:uploads] && session[:uploads][upload_id] || UploadProgress::Progress.new(0)
     end
 
+    # == THIS IS AN EXPERIMENTAL FEATURE
+    #
+    # Which means that it doesn't yet work on all systems. We're still working on full
+    # compatibility. It's thus not advised to use this unless you've verified it to work
+    # fully on all the systems that is a part of your environment. Consider this an extended
+    # preview.
+    #
     # Upload Progress abstracts the progress of an upload.  It's used by the
     # multipart progress IO that keeps track of the upload progress and creating
     # the application depends on.  It contians methods to update the progress
diff --git a/actionpack/lib/action_controller/vendor/xml_simple.rb b/actionpack/lib/action_controller/vendor/xml_simple.rb
index 3d8e283b44..e6ce63a839 100644
--- a/actionpack/lib/action_controller/vendor/xml_simple.rb
+++ b/actionpack/lib/action_controller/vendor/xml_simple.rb
@@ -7,14 +7,14 @@
 require 'rexml/document'
 
 # Easy API to maintain XML (especially configuration files).
-class XmlSimple
+class XmlSimple #:nodoc:
   include REXML
 
   @@VERSION = '1.0.2'
 
   # A simple cache for XML documents that were already transformed
   # by xml_in.
-  class Cache
+  class Cache #:nodoc:
     # Creates and initializes a new Cache object.
     def initialize
       @mem_share_cache = {}
diff --git a/actionpack/lib/action_controller/verification.rb b/actionpack/lib/action_controller/verification.rb
index 78918f800c..774af34532 100644
--- a/actionpack/lib/action_controller/verification.rb
+++ b/actionpack/lib/action_controller/verification.rb
@@ -1,37 +1,36 @@
 module ActionController #:nodoc:
-
-  # This module provides a class-level method for specifying that certain
-  # actions are guarded against being called without certain prerequisites
-  # being met. This is essentially a special kind of before_filter.
-  #
-  # An action may be guarded against being invoked without certain request
-  # parameters being set, or without certain session values existing.
-  #
-  # When a verification is violated, values may be inserted into the flash, and
-  # a specified redirection is triggered.
-  #
-  # Usage:
-  #
-  #   class GlobalController < ActionController::Base
-  #     # prevent the #update_settings action from being invoked unless
-  #     # the 'admin_privileges' request parameter exists.
-  #     verify :params => "admin_privileges", :only => :update_post,
-  #            :redirect_to => { :action => "settings" }
-  #
-  #     # disallow a post from being updated if there was no information
-  #     # submitted with the post, and if there is no active post in the
-  #     # session, and if there is no "note" key in the flash.
-  #     verify :params => "post", :session => "post", "flash" => "note",
-  #            :only => :update_post,
-  #            :add_flash => { "alert" => "Failed to create your message" },
-  #            :redirect_to => :category_url
-  #
-  module Verification
+  module Verification #:nodoc:
     def self.append_features(base) #:nodoc:
       super
       base.extend(ClassMethods)
     end
 
+    # This module provides a class-level method for specifying that certain
+    # actions are guarded against being called without certain prerequisites
+    # being met. This is essentially a special kind of before_filter.
+    #
+    # An action may be guarded against being invoked without certain request
+    # parameters being set, or without certain session values existing.
+    #
+    # When a verification is violated, values may be inserted into the flash, and
+    # a specified redirection is triggered.
+    #
+    # Usage:
+    #
+    #   class GlobalController < ActionController::Base
+    #     # prevent the #update_settings action from being invoked unless
+    #     # the 'admin_privileges' request parameter exists.
+    #     verify :params => "admin_privileges", :only => :update_post,
+    #            :redirect_to => { :action => "settings" }
+    #
+    #     # disallow a post from being updated if there was no information
+    #     # submitted with the post, and if there is no active post in the
+    #     # session, and if there is no "note" key in the flash.
+    #     verify :params => "post", :session => "post", "flash" => "note",
+    #            :only => :update_post,
+    #            :add_flash => { "alert" => "Failed to create your message" },
+    #            :redirect_to => :category_url
+    #
     module ClassMethods
       # Verify the given actions so that if certain prerequisites are not met,
       # the user is redirected to a different action. The +options+ parameter
diff --git a/actionpack/lib/action_view/helpers/upload_progress_helper.rb b/actionpack/lib/action_view/helpers/upload_progress_helper.rb
index 35972ebbd7..04b14c0c17 100644
--- a/actionpack/lib/action_view/helpers/upload_progress_helper.rb
+++ b/actionpack/lib/action_view/helpers/upload_progress_helper.rb
@@ -1,5 +1,12 @@
 module ActionView 
   module Helpers
+    # == THIS IS AN EXPERIMENTAL FEATURE
+    #
+    # Which means that it doesn't yet work on all systems. We're still working on full
+    # compatibility. It's thus not advised to use this unless you've verified it to work
+    # fully on all the systems that is a part of your environment. Consider this an extended
+    # preview.
+    #
     # Provides a set of methods to be used in your views to help with the
     # rendering of Ajax enabled status updating during a multipart upload.
     #
@@ -50,8 +57,7 @@ module ActionView
     # of the IDs and CSS classes used.
     #
     # Default styling is included with the scaffolding CSS.
-    #
-    module UploadProgressHelper #:nodoc:
+    module UploadProgressHelper
       unless const_defined? :FREQUENCY
         # Default number of seconds between client updates
         FREQUENCY = 2.0