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

actionpack/lib/action_controller/metal/http_authentication.rb

@@ -401,16 +401,20 @@ def request_http_token_authentication(realm = "Application")
         end
       end
 
-      # If token Authorization header is present, call the login procedure with
-      # the present token and options.
+      # If token Authorization header is present, call the login
+      # procedure with the present token and options.
       #
-      # controller      - ActionController::Base instance for the current request.
-      # login_procedure - Proc to call if a token is present. The Proc should
-      #                   take 2 arguments:
-      #                     authenticate(controller) { |token, options| ... }
+      # [controller]
+      #   ActionController::Base instance for the current request.
       #
-      # Returns the return value of `&login_procedure` if a token is found.
-      # Returns nil if no token is found.
+      # [login_procedure]
+      #   Proc to call if a token is present. The Proc should take two arguments:
+      #
+      #     authenticate(controller) { |token, options| ... }
+      #
+      # Returns the return value of <tt>login_procedure</tt> if a
+      # token is found. Returns <tt>nil</tt> if no token is found.
+
       def authenticate(controller, &login_procedure)
         token, options = token_and_options(controller.request)
         unless token.blank?

actionpack/lib/action_controller/metal/request_forgery_protection.rb

@@ -14,6 +14,20 @@ class InvalidAuthenticityToken < ActionControllerError #:nodoc:
   # authentication scheme there anyway). Also, GET requests are not protected as these
   # should be idempotent.
   #
+  # It's important to remember that XML or JSON requests are also affected and if
+  # you're building an API you'll need something like:
+  #
+  #   class ApplicationController < ActionController::Base
+  #     protect_from_forgery
+  #     skip_before_filter :verify_authenticity_token, :if => :json_request?
+  #
+  #     protected
+  #
+  #     def json_request?
+  #       request.format.json?
+  #     end
+  #   end
+  #
   # CSRF protection is turned on with the <tt>protect_from_forgery</tt> method,
   # which checks the token and resets the session if it doesn't match what was expected.
   # A call to this method is generated for new \Rails applications by default.

activemodel/lib/active_model/observer_array.rb

@@ -17,6 +17,11 @@ def disabled_for?(observer)
 
     # Disables one or more observers. This supports multiple forms:
     #
+    #   ORM.observers.disable :all
+    #     # => disables all observers for all models subclassed from 
+    #     #    an ORM base class that includes ActiveModel::Observing
+    #     #    e.g. ActiveRecord::Base
+    #
     #   ORM.observers.disable :user_observer
     #     # => disables the UserObserver
     #
@@ -27,9 +32,6 @@ def disabled_for?(observer)
     #   ORM.observers.disable :observer_1, :observer_2
     #     # => disables Observer1 and Observer2 for all models.
     #
-    #   ORM.observers.disable :all
-    #     # => disables all observers for all models.
-    #
     #   User.observers.disable :all do
     #     # all user observers are disabled for
     #     # just the duration of the block
@@ -40,6 +42,11 @@ def disable(*observers, &block)
 
     # Enables one or more observers. This supports multiple forms:
     #
+    #   ORM.observers.enable :all
+    #     # => enables all observers for all models subclassed from 
+    #     #    an ORM base class that includes ActiveModel::Observing
+    #     #    e.g. ActiveRecord::Base
+    #
     #   ORM.observers.enable :user_observer
     #     # => enables the UserObserver
     #
@@ -51,9 +58,6 @@ def disable(*observers, &block)
     #   ORM.observers.enable :observer_1, :observer_2
     #     # => enables Observer1 and Observer2 for all models.
     #
-    #   ORM.observers.enable :all
-    #     # => enables all observers for all models.
-    #
     #   User.observers.enable :all do
     #     # all user observers are enabled for
     #     # just the duration of the block

activemodel/lib/active_model/validations/exclusion.rb

@@ -30,8 +30,7 @@ module HelperMethods
       # * <tt>:in</tt> - An enumerable object of items that the value shouldn't be
       #   part of. This can be supplied as a proc or lambda which returns an
       #   enumerable. If the enumerable is a range the test is performed with
-      #   <tt>Range#cover?</tt> (backported in Active Support for 1.8), otherwise
-      #   with <tt>include?</tt>.
+      #   <tt>Range#cover?</tt>, otherwise with <tt>include?</tt>.
       # * <tt>:message</tt> - Specifies a custom error message (default is: "is
       #   reserved").
       # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute

activemodel/lib/active_model/validations/inclusion.rb

@@ -28,8 +28,8 @@ module HelperMethods
       # Configuration options:
       # * <tt>:in</tt> - An enumerable object of available items. This can be
       #   supplied as a proc or lambda which returns an enumerable. If the enumerable
-      #   is a range the test is performed with <tt>Range#cover?</tt>
-      #   (backported in Active Support for 1.8), otherwise with <tt>include?</tt>.
+      #   is a range the test is performed with <tt>Range#cover?</tt>, otherwise with
+      #   <tt>include?</tt>.
       # * <tt>:message</tt> - Specifies a custom error message (default is: "is not
       #   included in the list").
       # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute

activerecord/lib/active_record/store.rb

@@ -2,7 +2,7 @@
 
 module ActiveRecord
   # Store gives you a thin wrapper around serialize for the purpose of storing hashes in a single column.
-  # It's like a simple key/value store backed into your record when you don't care about being able to
+  # It's like a simple key/value store baked into your record when you don't care about being able to
   # query that store outside the context of a single record.
   #
   # You can then declare accessors to this store that are then accessible just like any other attribute

activesupport/lib/active_support/core_ext/object/try.rb

@@ -11,8 +11,6 @@ class Object
   # subclasses of +BasicObject+. For example, using try with +SimpleDelegator+ will
   # delegate +try+ to target instead of calling it on delegator itself.
   #
-  # ==== Examples
-  #
   # Without +try+
   #   @person && @person.name
   # or
@@ -27,7 +25,7 @@ class Object
   #
   # Without a method argument try will yield to the block unless the receiver is nil.
   #   @person.try { |p| "#{p.first_name} #{p.last_name}" }
-  #--
+  #
   # +try+ behaves like +Object#public_send+, unless called on +NilClass+.
   def try(*a, &b)
     if a.empty? && block_given?
@@ -42,8 +40,6 @@ class NilClass
   # Calling +try+ on +nil+ always returns +nil+.
   # It becomes specially helpful when navigating through associations that may return +nil+.
   #
-  # === Examples
-  #
   #   nil.try(:name) # => nil
   #
   # Without +try+

activesupport/lib/active_support/gzip.rb

@@ -2,7 +2,14 @@
 require 'stringio'
 
 module ActiveSupport
-  # A convenient wrapper for the zlib standard library that allows compression/decompression of strings with gzip.
+  # A convenient wrapper for the zlib standard library that allows
+  # compression/decompression of strings with gzip.
+  #
+  #   gzip = ActiveSupport::Gzip.compress('compress me!')
+  #   # => "\x1F\x8B\b\x00o\x8D\xCDO\x00\x03K\xCE\xCF-(J-.V\xC8MU\x04\x00R>n\x83\f\x00\x00\x00"
+  #
+  #   ActiveSupport::Gzip.decompress(gzip)
+  #   # => "compress me!" 
   module Gzip
     class Stream < StringIO
       def initialize(*)

activesupport/lib/active_support/json/decoding.rb

@@ -39,6 +39,14 @@ def with_backend(name)
         self.backend = old_backend
       end
 
+      # Returns the class of the error that will be raised when there is an error in decoding JSON.
+      # Using this method means you won't directly depend on the ActiveSupport's JSON implementation, in case it changes in the future.
+      #
+      #   begin
+      #     obj = ActiveSupport::JSON.decode(some_string)
+      #   rescue ActiveSupport::JSON.parse_error
+      #     Rails.logger.warn("Attempted to decode invalid JSON: #{some_string}")
+      #   end
       def parse_error
         MultiJson::DecodeError
       end