0
@@ -1,5 +1,7 @@
0
 *SVN*
0
 
0
+* Improve documentation. [Xavier Noria, leethal, jerome]
0
+
0
 * Ensure RJS redirect_to doesn't html-escapes string argument. Closes #8546 [josh, eventualbuddha, Pratik]
0
 
0
 * Support render :partial => collection of heterogeneous elements.  #11491 [Zach Dennis]

0
@@ -47,7 +47,7 @@
0
   #   :controller maps to your controller name
0
   #   :action     maps to an action with your controllers
0
   #
0
-  # Other names simply map to a parameter as in the case of +:id+.
0
+  # Other names simply map to a parameter as in the case of <tt>:id</tt>.
0
   #
0
   # == Route priority
0
   #
0
@@ -82,7 +82,7 @@
0
   # This sets up +blog+ as the default controller if no other is specified.
0
   # This means visiting '/' would invoke the blog controller.
0
   #
0
-  # More formally, you can define defaults in a route with the +:defaults+ key.
0
+  # More formally, you can define defaults in a route with the <tt>:defaults</tt> key.
0
   #
0
   #   map.connect ':controller/:action/:id', :action => 'show', :defaults => { :page => 'Dashboard' }
0
   #

0
@@ -716,11 +716,11 @@
0
           #   # Insert the rendered 'navigation' partial just before the DOM
0
           #   # element with ID 'content'.
0
           #   # Generates: new Insertion.Before("content", "-- Contents of 'navigation' partial --");
0
-          #   insert_html :before, 'content', :partial => 'navigation'
0
+          #   page.insert_html :before, 'content', :partial => 'navigation'
0
           #
0
           #   # Add a list item to the bottom of the <ul> with ID 'list'.
0
           #   # Generates: new Insertion.Bottom("list", "<li>Last item</li>");
0
-          #   insert_html :bottom, 'list', '<li>Last item</li>'
0
+          #   page.insert_html :bottom, 'list', '<li>Last item</li>'
0
           #
0
           def insert_html(position, id, *options_for_render)
0
             insertion = position.to_s.camelize
0
@@ -735,7 +735,7 @@
0
           #   # Replace the HTML of the DOM element having ID 'person-45' with the
0
           #   # 'person' partial for the appropriate object.
0
           #   # Generates:  Element.update("person-45", "-- Contents of 'person' partial --");
0
-          #   replace_html 'person-45', :partial => 'person', :object => @person
0
+          #   page.replace_html 'person-45', :partial => 'person', :object => @person
0
           #
0
           def replace_html(id, *options_for_render)
0
             call 'Element.update', id, render(*options_for_render)
0
@@ -749,7 +749,7 @@
0
           #
0
           #   # Replace the DOM element having ID 'person-45' with the
0
           #   # 'person' partial for the appropriate object.
0
-          #   replace 'person-45', :partial => 'person', :object => @person
0
+          #   page.replace 'person-45', :partial => 'person', :object => @person
0
           #
0
           # This allows the same partial that is used for the +insert_html+ to
0
           # be also used for the input to +replace+ without resorting to

0
@@ -86,7 +86,7 @@
0
       # of +options+. See the valid options in the documentation for
0
       # url_for. It's also possible to pass a string instead
0
       # of an options hash to get a link tag that uses the value of the string as the
0
-      # href for the link, or use +:back+ to link to the referrer - a JavaScript back
0
+      # href for the link, or use <tt>:back</tt> to link to the referrer - a JavaScript back
0
       # link will be used in place of a referrer if none exists. If nil is passed as
0
       # a name, the link itself will become the name.
0
       #

0
@@ -1,5 +1,7 @@
0
 *SVN*
0
 
0
+* Improve documentation. [Xavier Noria, Jack Danger Canty, leethal]
0
+
0
 * Tweak ActiveRecord::Base#to_json to include a root value in the returned hash: {"post": {"title": ...}} [rick]
0
 
0
   Post.find(1).to_json # => {"title": ...}

0
@@ -102,17 +102,10 @@
0
   {Learn more}[link:classes/ActiveRecord/Base.html]
0
 
0
 
0
-* Transaction support on both a database and object level. The latter is implemented 
0
-  by using Transaction::Simple[http://railsmanual.com/module/Transaction::Simple]
0
+* Transactions
0
 
0
-    # Just database transaction
0
+    # Database transaction
0
     Account.transaction do
0
-      david.withdrawal(100)
0
-      mary.deposit(100)
0
-    end
0
-
0
-    # Database and object transaction
0
-    Account.transaction(david, mary) do
0
       david.withdrawal(100)
0
       mary.deposit(100)
0
     end

0
@@ -136,7 +136,7 @@
0
     #   #others.create!(attributes={})    |   X   |    X     |    X
0
     #   #others.size                      |   X   |    X     |    X
0
     #   #others.length                    |   X   |    X     |    X
0
-    #   #others.count                     |       |    X     |    X
0
+    #   #others.count                     |   X   |    X     |    X
0
     #   #others.sum(args*,&block)         |   X   |    X     |    X
0
     #   #others.empty?                    |   X   |    X     |    X
0
     #   #others.clear                     |   X   |    X     |
0
@@ -150,9 +150,9 @@
0
     #
0
     # == Cardinality and associations
0
     #
0
-    # ActiveRecord associations can be used to describe relations with one-to-one, one-to-many
0
-    # and many-to-many cardinality. Each model uses an association to describe its role in
0
-    # the relation. In each case, the +belongs_to+ association is used in the model that has
0
+    # ActiveRecord associations can be used to describe one-to-one, one-to-many and many-to-many
0
+    # relationships between models. Each model uses an association to describe its role in
0
+    # the relation. The +belongs_to+ association is always used in the model that has
0
     # the foreign key.
0
     #
0
     # === One-to-one

0
@@ -1,5 +1,50 @@
0
 module ActiveRecord
0
   module Associations
0
+    # This is the root class of all association proxies:
0
+    #
0
+    #   AssociationProxy
0
+    #     BelongsToAssociation
0
+    #       HasOneAssociation
0
+    #     BelongsToPolymorphicAssociation
0
+    #     AssociationCollection
0
+    #       HasManyAssociation
0
+    #       HasAndBelongsToManyAssociation
0
+    #     HasManyThroughAssociation
0
+    #       HasOneThroughAssociation
0
+    #
0
+    # Association proxies in Active Record are middlemen between the object that
0
+    # holds the association, known as the <tt>@owner</tt>, and the actual associated
0
+    # object, known as the <tt>@target</tt>. The kind of association any proxy is
0
+    # about is available in <tt>@reflection</tt>. That's an instance of the class
0
+    # ActiveRecord::Reflection::AssociationReflection.
0
+    #
0
+    # For example, given
0
+    #
0
+    #   class Blog < ActiveRecord::Base
0
+    #     has_many :posts
0
+    #   end
0
+    #
0
+    #   blog = Blog.find(:first)
0
+    #
0
+    # the association proxy in <tt>blog.posts</tt> has the object in +blog+ as
0
+    # <tt>@owner</tt>, the collection of its posts as <tt>@target</tt>, and
0
+    # the <tt>@reflection</tt> object represents a <tt>:has_many</tt> macro.
0
+    #
0
+    # This class has most of the basic instance methods removed, and delegates
0
+    # unknown methods to <tt>@target</tt> via <tt>method_missing</tt>. As a
0
+    # corner case, it even removes the +class+ method and that's why you get
0
+    #
0
+    #   blog.posts.class # => Array
0
+    #
0
+    # though the object behind <tt>blog.posts</tt> is not an Array, but an
0
+    # ActiveRecord::Associations::HasManyAssociation.
0
+    #
0
+    # The <tt>@target</tt> object is not loaded until needed. For example,
0
+    #
0
+    #   blog.posts.count
0
+    #
0
+    # is computed directly through SQL and does not trigger by itself the
0
+    # instantiation of the actual post records.
0
     class AssociationProxy #:nodoc:
0
       alias_method :proxy_respond_to?, :respond_to?
0
       alias_method :proxy_extend, :extend

0
@@ -191,6 +191,10 @@
0
   #
0
   #   Student.find(:all, :conditions => { :grade => 9..12 })
0
   #
0
+  # An array may be used in the hash to use the SQL IN operator:
0
+  #
0
+  #   Student.find(:all, :conditions => { :grade => [9,11,12] })
0
+  #
0
   # == Overwriting default accessors
0
   #
0
   # All column values are automatically available through basic accessors on the Active Record object, but sometimes you
0
@@ -488,6 +492,7 @@
0
       # Examples for find all:
0
       #   Person.find(:all) # returns an array of objects for all the rows fetched by SELECT * FROM people
0
       #   Person.find(:all, :conditions => [ "category IN (?)", categories], :limit => 50)
0
+      #   Person.find(:all, :conditions => { :friends => ["Bob", "Steve", "Fred"] }
0
       #   Person.find(:all, :offset => 10, :limit => 10)
0
       #   Person.find(:all, :include => [ :account, :friends ])
0
       #   Person.find(:all, :group => "category")

0
@@ -161,12 +161,12 @@
0
       # an Array of Symbols.
0
       #
0
       # The index will be named after the table and the first column name,
0
-      # unless you pass +:name+ as an option.
0
+      # unless you pass <tt>:name</tt> as an option.
0
       #
0
       # When creating an index on multiple columns, the first column is used as a name
0
       # for the index. For example, when you specify an index on two columns
0
-      # [+:first+, +:last+], the DBMS creates an index for both columns as well as an
0
-      # index for the first column +:first+. Using just the first name for this index
0
+      # [<tt>:first</tt>, <tt>:last</tt>], the DBMS creates an index for both columns as well as an
0
+      # index for the first column <tt>:first</tt>. Using just the first name for this index
0
       # makes sense, because you will never have to create a singular index with this
0
       # name.
0
       #

0
@@ -76,34 +76,39 @@
0
         @macro, @name, @options, @active_record = macro, name, options, active_record
0
       end
0
 
0
-      # Returns the name of the macro, so it would return :balance for "composed_of :balance, :class_name => 'Money'" or
0
-      # :clients for "has_many :clients".
0
+      # Returns the name of the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return
0
+      # <tt>:balance</tt> or for <tt>has_many :clients</tt> it will return <tt>:clients</tt>.
0
       def name
0
         @name
0
       end
0
 
0
-      # Returns the type of the macro, so it would return :composed_of for
0
-      # "composed_of :balance, :class_name => 'Money'" or :has_many for "has_many :clients".
0
+      # Returns the macro type. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return <tt>:composed_of</tt>
0
+      # or for <tt>has_many :clients</tt> will return <tt>:has_many</tt>.
0
       def macro
0
         @macro
0
       end
0
 
0
-      # Returns the hash of options used for the macro, so it would return { :class_name => "Money" } for
0
-      # "composed_of :balance, :class_name => 'Money'" or {} for "has_many :clients".
0
+      # Returns the hash of options used for the macro.  For example, it would return <tt>{ :class_name => "Money" }</tt> for
0
+      # <tt>composed_of :balance, :class_name => 'Money'</tt> or +{}+ for <tt>has_many :clients</tt>.
0
+
0
       def options
0
         @options
0
       end
0
 
0
-      # Returns the class for the macro, so "composed_of :balance, :class_name => 'Money'" returns the Money class and
0
-      # "has_many :clients" returns the Client class.
0
+      # Returns the class for the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns the +Money+
0
+      # class and <tt>has_many :clients</tt> returns the +Client+ class.
0
       def klass
0
         @klass ||= class_name.constantize
0
       end
0
 
0
+      # Returns the class name for the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns <tt>'Money'</tt>
0
+      # and <tt>has_many :clients</tt> returns <tt>'Client'</tt>.
0
       def class_name
0
         @class_name ||= options[:class_name] || derive_class_name
0
       end
0
 
0
+      # Returns +true+ if +self+ and +other_aggregation+ have the same +name+ attribute, +active_record+ attribute,
0
+      # and +other_aggregation+ has an options hash assigned to it.
0
       def ==(other_aggregation)
0
         name == other_aggregation.name && other_aggregation.options && active_record == other_aggregation.active_record
0
       end

0
@@ -28,7 +28,7 @@
0
     #
0
     # This example will only take money from David and give to Mary if neither +withdrawal+ nor +deposit+ raises an exception.
0
     # Exceptions will force a ROLLBACK that returns the database to the state before the transaction was begun. Be aware, though,
0
-    # that the objects by default will _not_ have their instance data returned to their pre-transactional state.
0
+    # that the objects  will _not_ have their instance data returned to their pre-transactional state.
0
     #
0
     # == Different ActiveRecord classes in a single transaction
0
     #

0
@@ -723,7 +723,7 @@
0
       #
0
       # Configuration options:
0
       # * <tt>in</tt> - An enumerable object of available items
0
-      # * <tt>message</tt> - Specifies a customer error message (default is: "is not included in the list")
0
+      # * <tt>message</tt> - Specifies a custom error message (default is: "is not included in the list")
0
       # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false)
0
       # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false)
0
       # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
0
@@ -755,7 +755,7 @@
0
       #
0
       # Configuration options:
0
       # * <tt>in</tt> - An enumerable object of items that the value shouldn't be part of
0
-      # * <tt>message</tt> - Specifies a customer error message (default is: "is reserved")
0
+      # * <tt>message</tt> - Specifies a custom error message (default is: "is reserved")
0
       # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false)
0
       # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false)
0
       # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should

0
@@ -1,5 +1,7 @@
0
 *SVN*
0
 
0
+* Improve documentation. [Xavier Noria]
0
+
0
 * Fixed that to_param should be used and honored instead of hardcoding the id #11406 [gspiers]
0
 
0
 * Improve documentation. [Radar, Jan De Poorter, chuyeow, xaviershay, danger, miloops, Xavier Noria,  Sunny Ripert]

0
@@ -3,9 +3,8 @@
0
     module Array #:nodoc:
0
       # Makes it easier to access parts of an array.
0
       module Access
0
-        # Returns the remaining of the array from the +position+.
0
+        # Returns the tail of the array from +position+.
0
         #
0
-        # Examples: 
0
         #   %w( a b c d ).from(0)  # => %w( a b c d )
0
         #   %w( a b c d ).from(2)  # => %w( c d )
0
         #   %w( a b c d ).from(10) # => nil
0
0
@@ -13,9 +12,8 @@
0
           self[position..-1]
0
         end
0
         
0
-        # Returns the beginning of the array up to the +position+.
0
+        # Returns the beginning of the array up to  +position+.
0
         #
0
-        # Examples: 
0
         #   %w( a b c d ).to(0)  # => %w( a )
0
         #   %w( a b c d ).to(2)  # => %w( a b c )
0
         #   %w( a b c d ).to(10) # => %w( a b c d )

0
@@ -30,11 +30,9 @@
0
           map(&:to_param).join '/'
0
         end
0
 
0
-        # Converts an array into a string suitable for use as a URL query string, using the given <tt>key</tt> as the
0
-        # param name.
0
+        # Converts an array into a string suitable for use as a URL query string,
0
+        # using the given +key+ as the param name.
0
         #
0
-        # Example:
0
-        #
0
         #   ['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding"
0
         def to_query(key)
0
           collect { |value| value.to_query("#{key}[]") } * '&'
0
@@ -80,8 +78,6 @@
0
         # Otherwise the root element is "records".
0
         #
0
         # Root children have as node name the one of the root singularized.
0
-        #
0
-        # Example:
0
         #
0
         #   [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml
0
         #

0
@@ -2,7 +2,8 @@
0
   module CoreExtensions #:nodoc:
0
     module Array #:nodoc:
0
       module ExtractOptions
0
-        # Extract options from a set of arguments. Removes and returns the last element in the array if it's a hash, otherwise returns a blank hash.
0
+        # Extracts options from a set of arguments. Removes and returns the last
0
+        # element in the array if it's a hash, otherwise returns a blank hash.
0
         #
0
         #   def options(*args)
0
         #     args.extract_options!

0
@@ -4,12 +4,9 @@
0
   module CoreExtensions #:nodoc:
0
     module Array #:nodoc:
0
       module Grouping
0
-        # Iterate over an array in groups of a certain size, padding any remaining 
0
-        # slots with specified value (<tt>nil</tt> by default) unless it is
0
-        # <tt>false</tt>.
0
+        # Iterates over the array in groups of size +number+, padding any remaining 
0
+        # slots with +fill_with+ unless it is +false+.
0
         # 
0
-        # Examples:
0
-        # 
0
         #   %w(1 2 3 4 5 6 7).in_groups_of(3) {|g| p g}
0
         #   ["1", "2", "3"]
0
         #   ["4", "5", "6"]
0
0
@@ -42,10 +39,8 @@
0
           end
0
         end
0
 
0
-        # Divide the array into one or more subarrays based on a delimiting +value+
0
+        # Divides the array into one or more subarrays based on a delimiting +value+
0
         # or the result of an optional block.
0
-        #
0
-        # Examples:
0
         #
0
         #   [1, 2, 3, 4, 5].split(3)                # => [[1, 2], [4, 5]]
0
         #   (1..10).to_a.split { |i| i % 3 == 0 }   # => [[1, 2], [4, 5], [7, 8], [10]]

0
@@ -2,7 +2,7 @@
0
   module CoreExtensions #:nodoc:
0
     module Array #:nodoc:
0
       module RandomAccess
0
-        # Return a random element from the array.
0
+        # Returns a random element from the array.
0
         def rand
0
           self[Kernel.rand(length)]
0
         end

0
@@ -1,10 +1,13 @@
0
 class Object
0
   # An object is blank if it's false, empty, or a whitespace string.
0
-  # For example, "", "   ", nil, [], and {} are blank.
0
+  # For example, "", "   ", +nil+, [], and {} are blank.
0
   #
0
   # This simplifies
0
+  #
0
   #   if !address.nil? && !address.empty?
0
+  #
0
   # to
0
+  #
0
   #   if !address.blank?
0
   def blank?
0
     respond_to?(:empty?) ? empty? : !self

0
@@ -1,21 +1,38 @@
0
 class Class #:nodoc:
0
   
0
-  # Will unassociate the class with its subclasses as well as uninitializing the subclasses themselves.
0
-  # >> Integer.remove_subclasses
0
-  # => [Bignum, Fixnum]
0
-  # >> Fixnum
0
-  # NameError: uninitialized constant Fixnum
0
+  # Unassociates the class with its subclasses and removes the subclasses
0
+  # themselves.
0
+  #
0
+  #   Integer.remove_subclasses # => [Bignum, Fixnum]
0
+  #   Fixnum                    # => NameError: uninitialized constant Fixnum
0
   def remove_subclasses
0
     Object.remove_subclasses_of(self)
0
   end
0
 
0
-  # Returns a list of classes that inherit from this class in an array.
0
-  # Example: Integer.subclasses => ["Bignum", "Fixnum"]
0
+  # Returns an array with the names of the subclasses of +self+ as strings.
0
+  #
0
+  #   Integer.subclasses # => ["Bignum", "Fixnum"]
0
   def subclasses
0
     Object.subclasses_of(self).map { |o| o.to_s }
0
   end
0
 
0
-  # Allows you to remove individual subclasses or a selection of subclasses from a class without removing all of them.
0
+  # Removes the classes in +klasses+ from their parent module.
0
+  #
0
+  # Ordinary classes belong to some module via a constant. This method computes
0
+  # that constant name from the class name and removes it from the module it
0
+  # belongs to.
0
+  #
0
+  #   Object.remove_class(Integer) # => [Integer]
0
+  #   Integer                      # => NameError: uninitialized constant Integer
0
+  #
0
+  # Take into account that in general the class object could be still stored
0
+  # somewhere else.
0
+  #
0
+  #   i = Integer                  # => Integer
0
+  #   Object.remove_class(Integer) # => [Integer]
0
+  #   Integer                      # => NameError: uninitialized constant Integer
0
+  #   i.subclasses                 # => ["Bignum", "Fixnum"]
0
+  #   Fixnum.superclass            # => Integer
0
   def remove_class(*klasses)
0
     klasses.flatten.each do |klass|
0
       # Skip this class if there is nothing bound to this name

0
@@ -16,12 +16,12 @@
0
         end
0
 
0
         module ClassMethods
0
-          # Finds yesterday's date, in the format similar to: Mon, 17 Mar 2008
0
+          # Returns a new Date representing the date 1 day ago (i.e. yesterday's date).
0
           def yesterday
0
             ::Date.today.yesterday
0
           end
0
           
0
-          # Finds tommorrow's date, in the format similar to: Tue, 18 Mar 2008
0
+          # Returns a new Date representing the date 1 day after today (i.e. tomorrow's date).
0
           def tomorrow
0
             ::Date.today.tomorrow
0
           end

0
@@ -45,7 +45,7 @@
0
           formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
0
         end
0
 
0
-        # Returns the utc_offset as an +HH:MM formatted string. Examples:
0
+        # Returns the +utc_offset+ as an +HH:MM formatted string. Examples:
0
         #
0
         #   datetime = DateTime.civil(2000, 1, 1, 0, 0, 0, Rational(-6, 24))
0
         #   datetime.formatted_offset         # => "-06:00"