Merge branch 'master' of git://github.com/lifo/docrails

5 files changed, 57 insertions, 29 deletions

diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb
index c38e9ef2c4..f3f7cb6507 100644
--- a/actionpack/lib/action_dispatch/routing/mapper.rb
+++ b/actionpack/lib/action_dispatch/routing/mapper.rb
@@ -247,7 +247,7 @@ module ActionDispatch
         #
         #   root :to => 'pages#main'
         #
-        # For options, see the +match+ method's documentation, as +root+ uses it internally.
+        # For options, see +match+, as +root+ uses it internally.
         #
         # You should put the root route at the top of <tt>config/routes.rb</tt>,
         # because this means it will be matched first. As this is the most popular route
@@ -256,24 +256,41 @@ module ActionDispatch
           match '/', options.reverse_merge(:as => :root)
         end
 
-        # Matches a pattern to one or more urls. Any symbols in a pattern are
-        # interpreted as url parameters:
+        # Matches a url pattern to one or more routes. Any symbols in a pattern
+        # are interpreted as url query parameters and thus available as +params+
+        # in an action:
         #
-        #   # sets parameters :controller, :action and :id
+        #   # sets :controller, :action and :id in params
         #   match ':controller/:action/:id'
         #
-        # Two of these symbols are special: <tt>:controller</tt> maps to the
-        # controller name and <tt>:action</tt> to the action name within that
-        # controller. Anything other than <tt>:controller</tt> or
-        # <tt>:action</tt> will be available to the action as part of +params+.
-        # If a pattern does not have :controller and :action symbols, then they
-        # must be set in options or shorthand. For example:
+        # Two of these symbols are special, +:controller+ maps to the controller
+        # and +:action+ to the controller's action. A pattern can also map
+        # wildcard segments (globs) to params:
+        #
+        #   match 'songs/*category/:title' => 'songs#show'
+        #
+        #   # 'songs/rock/classic/stairway-to-heaven' sets
+        #   #  params[:category] = 'rock/classic'
+        #   #  params[:title] = 'stairway-to-heaven'
+        #
+        # When a pattern points to an internal route, the route's +:action+ and
+        # +:controller+ should be set in options or hash shorthand. Examples:
         #
         #   match 'photos/:id' => 'photos#show'
         #   match 'photos/:id', :to => 'photos#show'
         #   match 'photos/:id', :controller => 'photos', :action => 'show'
         #
-        # === Supported options
+        # A pattern can also point to a +Rack+ endpoint i.e. anything that
+        # responds to +call+:
+        #
+        #   match 'photos/:id' => lambda {|hash| [200, {}, "Coming soon" }
+        #   match 'photos/:id' => PhotoRackApp
+        #   # Yes, controller actions are just rack endpoints
+        #   match 'photos/:id' => PhotosController.action(:show)
+        #
+        # === Options
+        #
+        # Any options not seen here are passed on as params with the url.
         #
         # [:controller]
         #   The route's controller.
@@ -302,9 +319,12 @@ module ActionDispatch
         #      match 'path' => 'c#a', :via => [:get, :post]
         #
         # [:to]
-        #   Shorthand for specifying :controller and :action.
+        #   Points to a +Rack+ endpoint. Can be an object that responds to
+        #   +call+ or a string representing a controller's action.
         #
-        #      match 'path' => 'c#a', :to => 'controller#action'
+        #      match 'path', :to => 'controller#action'
+        #      match 'path', :to => lambda { [200, {}, "Success!"] }
+        #      match 'path', :to => RackApp
         #
         # [:on]
         #   Shorthand for wrapping routes in a specific RESTful context. Valid
@@ -358,6 +378,8 @@ module ActionDispatch
         #
         #   mount(SomeRackApp => "some_route")
         #
+        # For options, see +match+, as +mount+ uses it internally.
+        #
         # All mounted applications come with routing helpers to access them.
         # These are named after the class specified, so for the above example
         # the helper is either +some_rack_app_path+ or +some_rack_app_url+.
@@ -549,7 +571,7 @@ module ActionDispatch
         # The difference here being that the routes generated are like /rails/projects/2,
         # rather than /accounts/rails/projects/2.
         #
-        # === Supported options
+        # === Options
         #
         # Takes same options as <tt>Base#match</tt> and <tt>Resources#resources</tt>.
         #
@@ -632,7 +654,7 @@ module ActionDispatch
         #        admin_post PUT    /admin/posts/:id(.:format)      {:action=>"update", :controller=>"admin/posts"}
         #        admin_post DELETE /admin/posts/:id(.:format)      {:action=>"destroy", :controller=>"admin/posts"}
         #
-        # === Supported options
+        # === Options
         #
         # The +:path+, +:as+, +:module+, +:shallow_path+ and +:shallow_prefix+
         # options all default to the name of the namespace.
@@ -950,7 +972,7 @@ module ActionDispatch
         #   PUT     /geocoder
         #   DELETE  /geocoder
         #
-        # === Supported options
+        # === Options
         # Takes same options as +resources+.
         def resource(*resources, &block)
           options = resources.extract_options!
@@ -1013,7 +1035,7 @@ module ActionDispatch
         #   PUT     /photos/:id/comments/:id
         #   DELETE  /photos/:id/comments/:id
         #
-        # === Supported options
+        # === Options
         # Takes same options as <tt>Base#match</tt> as well as:
         #
         # [:path_names]
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index d30362b93e..398936b3d8 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -912,7 +912,7 @@ module ActiveRecord
       # * <tt>Firm#clients.create</tt> (similar to <tt>c = Client.new("firm_id" => id); c.save; c</tt>)
       # The declaration can also include an options hash to specialize the behavior of the association.
       #
-      # === Supported options
+      # === Options
       # [:class_name]
       #   Specify the class name of the association. Use it only if that name can't be inferred
       #   from the association name. So <tt>has_many :products</tt> will by default be linked
diff --git a/activerecord/lib/active_record/relation/finder_methods.rb b/activerecord/lib/active_record/relation/finder_methods.rb
index e447de92a4..7f32e5538e 100644
--- a/activerecord/lib/active_record/relation/finder_methods.rb
+++ b/activerecord/lib/active_record/relation/finder_methods.rb
@@ -19,7 +19,7 @@ module ActiveRecord
     #
     # All approaches accept an options hash as their last parameter.
     #
-    # ==== Parameters
+    # ==== Options
     #
     # * <tt>:conditions</tt> - An SQL fragment like "administrator = 1", <tt>["user_name = ?", username]</tt>,
     #   or <tt>["user_name = :user_name", { :user_name => user_name }]</tt>. See conditions in the intro.
diff --git a/activerecord/lib/active_record/timestamp.rb b/activerecord/lib/active_record/timestamp.rb
index 65d9d1fb19..1511c71ffc 100644
--- a/activerecord/lib/active_record/timestamp.rb
+++ b/activerecord/lib/active_record/timestamp.rb
@@ -9,24 +9,26 @@ module ActiveRecord
   #
   # Timestamping can be turned off by setting:
   #
-  #   <tt>ActiveRecord::Base.record_timestamps = false</tt>
+  #   config.active_record.record_timestamps = false
   #
   # Timestamps are in the local timezone by default but you can use UTC by setting:
   #
-  #   <tt>ActiveRecord::Base.default_timezone = :utc</tt>
+  #   config.active_record.default_timezone = :utc
   #
   # == Time Zone aware attributes
   #
   # By default, ActiveRecord::Base keeps all the datetime columns time zone aware by executing following code.
   #
-  #   ActiveRecord::Base.time_zone_aware_attributes = true
+  #   config.active_record.time_zone_aware_attributes = true
   #
   # This feature can easily be turned off by assigning value <tt>false</tt> .
   #
-  # If your attributes are time zone aware and you desire to skip time zone conversion for certain
-  # attributes then you can do following:
+  # If your attributes are time zone aware and you desire to skip time zone conversion to the current Time.zone
+  # when reading certain attributes then you can do following:
   #
-  #   Topic.skip_time_zone_conversion_for_attributes = [:written_on]
+  #   class Topic < ActiveRecord::Base
+  #     self.skip_time_zone_conversion_for_attributes = [:written_on]
+  #   end
   module Timestamp
     extend ActiveSupport::Concern
 
diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb
index ef401a6d18..ff90d7ca58 100644
--- a/activesupport/lib/active_support/core_ext/time/zones.rb
+++ b/activesupport/lib/active_support/core_ext/time/zones.rb
@@ -19,14 +19,18 @@ class Time
     # * A TZInfo::Timezone object.
     # * An identifier for a TZInfo::Timezone object (e.g., "America/New_York").
     #
-    # Here's an example of how you might set <tt>Time.zone</tt> on a per request basis -- <tt>current_user.time_zone</tt>
-    # just needs to return a string identifying the user's preferred TimeZone:
+    # Here's an example of how you might set <tt>Time.zone</tt> on a per request basis and reset it when the request is done.
+    # <tt>current_user.time_zone</tt> just needs to return a string identifying the user's preferred time zone:
     #
     #   class ApplicationController < ActionController::Base
-    #     before_filter :set_time_zone
+    #     around_filter :set_time_zone
     #
     #     def set_time_zone
-    #       Time.zone = current_user.time_zone
+    #       old_time_zone = Time.zone
+    #       Time.zone = current_user.time_zone if logged_in?
+    #       yield
+    #     ensure
+    #       Time.zone = old_time_zone
     #     end
     #   end
     def zone=(time_zone)