Merge remote branch 'docrails/master'

actionpack/README.rdoc

@@ -1,6 +1,6 @@
 = Action Pack -- From request to response
 
-Action Pack is a framework for handling and responding to web requests. It it
+Action Pack is a framework for handling and responding to web requests. It
 provides mechanisms for *routing* (mapping request URLs to actions), defining
 *controllers* that implement actions, and generating responses by rendering
 *views*, which are templates of various formats. In short, Action Pack

activemodel/lib/active_model/errors.rb

@@ -37,11 +37,11 @@ module ActiveModel
   #       send(attr)
   #     end
   #   
-  #     def ErrorsPerson.human_attribute_name(attr, options = {})
+  #     def Person.human_attribute_name(attr, options = {})
   #       attr
   #     end
   #   
-  #     def ErrorsPerson.lookup_ancestors
+  #     def Person.lookup_ancestors
   #       [self]
   #     end
   #   

activemodel/lib/active_model/serialization.rb

@@ -61,6 +61,8 @@ module ActiveModel
   #   person.serializable_hash   # => {"name"=>"Bob"}
   #   person.to_json             # => "{\"name\":\"Bob\"}"
   #   person.to_xml              # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
+  #
+  # Valid options are <tt>:only</tt>, <tt>:except</tt> and <tt>:methods</tt> .  
   module Serialization
     def serializable_hash(options = nil)
       options ||= {}

activerecord/lib/active_record/associations/has_many_association.rb

@@ -24,7 +24,7 @@ module ActiveRecord
         # If the association has a counter cache it gets that value. Otherwise
         # it will attempt to do a count via SQL, bounded to <tt>:limit</tt> if
         # there's one.  Some configuration options like :group make it impossible
-        # to do a SQL count, in those cases the array count will be used.
+        # to do an SQL count, in those cases the array count will be used.
         #
         # That does not depend on whether the collection has already been loaded
         # or not. The +size+ method is the one that takes the loaded flag into

activerecord/lib/active_record/base.rb

@@ -516,7 +516,8 @@ module ActiveRecord #:nodoc:
         connection.select_value(sql, "#{name} Count").to_i
       end
 
-      # Attributes listed as readonly can be set for a new record, but will be ignored in database updates afterwards.
+      # Attributes listed as readonly will be used to create a new record but update operations will
+      # ignore these fields.
       def attr_readonly(*attributes)
         write_inheritable_attribute(:attr_readonly, Set.new(attributes.map(&:to_s)) + (readonly_attributes || []))
       end
@@ -604,8 +605,8 @@ module ActiveRecord #:nodoc:
         (parents.detect{ |p| p.respond_to?(:table_name_prefix) } || self).table_name_prefix
       end
 
-      # Defines the column name for use with single table inheritance
-      # -- can be set in subclasses like so: self.inheritance_column = "type_id"
+      # Defines the column name for use with single table inheritance. Use 
+      # <tt>set_inheritance_column</tt> to set a different value.
       def inheritance_column
         @inheritance_column ||= "type".freeze
       end
@@ -622,8 +623,8 @@ module ActiveRecord #:nodoc:
         default
       end
 
-      # Sets the table name to use to the given value, or (if the value
-      # is nil or false) to the value returned by the given block.
+      # Sets the table name. If the value is nil or false  then the value returned by the given 
+      # block is used.
       #
       #   class Project < ActiveRecord::Base
       #     set_table_name "project"
@@ -1034,8 +1035,8 @@ module ActiveRecord #:nodoc:
         end
 
       protected
-        # Scope parameters to method calls within the block.  Takes a hash of method_name => parameters hash.
-        # method_name may be <tt>:find</tt> or <tt>:create</tt>. <tt>:find</tt> parameter is <tt>Relation</tt> while
+        # with_scope lets you apply options to inner block incrementally. It takes a hash and the keys must be
+        # <tt>:find</tt> or <tt>:create</tt>. <tt>:find</tt> parameter is <tt>Relation</tt> while
         # <tt>:create</tt> parameters are an attributes hash.
         #
         #   class Article < ActiveRecord::Base
@@ -1080,8 +1081,7 @@ module ActiveRecord #:nodoc:
         #     end
         #   end
         #
-        # *Note*: the +:find+ scope also has effect on update and deletion methods,
-        # like +update_all+ and +delete_all+.
+        # *Note*: the +:find+ scope also has effect on update and deletion methods, like +update_all+ and +delete_all+.
         def with_scope(method_scoping = {}, action = :merge, &block)
           method_scoping = method_scoping.method_scoping if method_scoping.respond_to?(:method_scoping)
 

activerecord/lib/active_record/callbacks.rb

@@ -68,8 +68,8 @@ module ActiveRecord
   #   end
   #
   # Now, when <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> is 
-  # run, both +destroy_author+ and +destroy_readers+ are called. Contrast this to the situation where 
-  # we've implemented the save behavior through overwriteable methods:
+  # run, both +destroy_author+ and +destroy_readers+ are called. Contrast this to the following situation 
+  # where the +before_destroy+ methis is overriden:
   #
   #   class Topic < ActiveRecord::Base
   #     def before_destroy() destroy_author end

activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb

@@ -42,7 +42,7 @@ module ActiveRecord
         65535
       end
 
-      # the maximum length of a SQL query
+      # the maximum length of an SQL query
       def sql_query_length
         1048575
       end

activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb

@@ -537,7 +537,7 @@ module ActiveRecord
         end
     end
 
-    # Represents a SQL table in an abstract way for updating a table.
+    # Represents an SQL table in an abstract way for updating a table.
     # Also see TableDefinition and SchemaStatements#create_table
     #
     # Available transformations are:

activerecord/lib/active_record/connection_adapters/mysql_adapter.rb

@@ -278,7 +278,7 @@ module ActiveRecord
         rows
       end
 
-      # Executes a SQL query and returns a MySQL::Result object. Note that you have to free 
+      # Executes an SQL query and returns a MySQL::Result object. Note that you have to free 
       # the Result object after you're done using it.
       def execute(sql, name = nil) #:nodoc:
         if name == :skip_logging

activerecord/lib/active_record/persistence.rb

@@ -60,7 +60,7 @@ module ActiveRecord
     # reflect that no changes should be made (since they can't be
     # persisted). Returns the frozen instance.
     #
-    # The row is simply removed with a SQL +DELETE+ statement on the
+    # The row is simply removed with an SQL +DELETE+ statement on the
     # record's primary key, and no callbacks are executed.
     #
     # To enforce the object's +before_destroy+ and +after_destroy+

activerecord/lib/active_record/railties/databases.rake

@@ -339,7 +339,7 @@ namespace :db do
   end
 
   namespace :structure do
-    desc "Dump the database structure to a SQL file"
+    desc "Dump the database structure to an SQL file"
     task :dump => :environment do
       abcs = ActiveRecord::Base.configurations
       case abcs[Rails.env]["adapter"]

activesupport/lib/active_support/callbacks.rb

@@ -571,7 +571,9 @@ module ActiveSupport
       #
       # would trigger <tt>Audit#before_save</tt> instead. That's constructed by calling
       # <tt>"#{kind}_#{name}"</tt> on the given instance. In this case "kind" is "before" and
-      # "name" is "save".
+      # "name" is "save". In this context treat ":kind" and ":name" as special thing where
+      # ":kind" refers to "callback type(before/after)" and ":name" refers to the method on 
+      # which callbacks are being defined.
       #
       # A declaration like
       #

activesupport/lib/active_support/concern.rb

@@ -1,3 +1,38 @@
+# A typical module looks like this
+#
+#   module M
+#     def self.included(base)
+#       base.send(:extend, ClassMethods)
+#       base.send(:include, InstanceMethods)
+#       scope :foo, :conditions => {:created_at => nil}
+#     end
+#
+#     module ClassMethods
+#       def cm; puts 'I am class method'; end
+#     end
+#
+#     module InstanceMethods
+#       def im; puts 'I am instance method'; end
+#     end
+#   end
+#
+# By using <tt>ActiveSupport::Concern</tt> above module could be written as:
+#
+#   module M
+#     extend ActiveSupport::Concern
+#
+#    included do 
+#       scope :foo, :conditions => {:created_at => nil}
+#     end
+#
+#     module ClassMethods
+#       def cm; puts 'I am class method'; end
+#     end
+#
+#     module InstanceMethods
+#       def im; puts 'I am instance method'; end
+#     end
+#   end
 module ActiveSupport
   module Concern
     def self.extended(base)

railties/guides/source/api_documentation_guidelines.textile

@@ -29,7 +29,7 @@ Documentation has to be concise but comprehensive. Explore and document edge cas
 
 The proper names of Rails components have a space in between the words, like "Active Support". +ActiveRecord+ is a Ruby module, whereas Active Record is an ORM. Historically there has been lack of consistency regarding this, but we checked with David when docrails started. All Rails documentation consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be fenomenal :).
 
-Spell names correctly: HTML, MySQL, JavaScript, ERb.
+Spell names correctly: HTML, MySQL, JavaScript, ERb. Use the article "an" for "SQL", as in "an SQL statement". Also "an SQLite database".
 
 h3. Example Code
 

railties/guides/source/getting_started.textile

@@ -213,9 +213,9 @@ If you open this file in a new Rails application, you'll see a default database
 * The +test+ environment is used to run automated tests
 * The +production+ environment is used when you deploy your application for the world to use.
 
-h5. Configuring a SQLite3 Database
+h5. Configuring an SQLite3 Database
 
-Rails comes with built-in support for "SQLite3":http://www.sqlite.org, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using a SQLite database when creating a new project, but you can always change it later.
+Rails comes with built-in support for "SQLite3":http://www.sqlite.org, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using an SQLite database when creating a new project, but you can always change it later.
 
 Here's the section of the default configuration file (<tt>config/database.yml</tt>) with connection information for the development environment:
 

railties/lib/rails/generators/rails/app/templates/config/databases/oracle.yml

@@ -4,7 +4,7 @@
 #  http://rubyforge.org/projects/ruby-oci8/
 #
 # Specify your database using any valid connection syntax, such as a
-# tnsnames.ora service name, or a SQL connect url string of the form:
+# tnsnames.ora service name, or an SQL connect string of the form:
 #
 #   //host:[port][/service name]
 #

railties/lib/rails/railtie.rb

@@ -6,53 +6,53 @@ require 'active_support/deprecation'
 module Rails
   # Railtie is the core of the Rails Framework and provides several hooks to extend
   # Rails and/or modify the initialization process.
-  # 
+  #
   # Every major component of Rails (Action Mailer, Action Controller,
   # Action View, Active Record and Active Resource) are all Railties, so each of
   # them is responsible to set their own initialization. This makes, for example,
   # Rails absent of any Active Record hook, allowing any other ORM framework to hook in.
-  # 
+  #
   # Developing a Rails extension does _not_ require any implementation of
   # Railtie, but if you need to interact with the Rails framework during
   # or after boot, then Railtie is what you need to do that interaction.
-  # 
+  #
   # For example, the following would need you to implement Railtie in your
   # plugin:
-  # 
+  #
   # * creating initializers
   # * configuring a Rails framework or the Application, like setting a generator
   # * adding Rails config.* keys to the environment
   # * setting up a subscriber to the Rails +ActiveSupport::Notifications+
   # * adding rake tasks into rails
-  # 
+  #
   # == Creating your Railtie
   #
   # Implementing Railtie in your Rails extension is done by creating a class
   # Railtie that has your extension name and making sure that this gets loaded
   # during boot time of the Rails stack.
-  # 
+  #
   # You can do this however you wish, but here is an example if you want to provide
   # it for a gem that can be used with or without Rails:
-  # 
+  #
   # * Create a file (say, lib/my_gem/railtie.rb) which contains class Railtie inheriting from
   #   Rails::Railtie and is namespaced to your gem:
   #
-  #   # lib/my_gem/railtie.rb
-  #   module MyGem
-  #     class Railtie < Rails::Railtie
+  #     # lib/my_gem/railtie.rb
+  #     module MyGem
+  #       class Railtie < Rails::Railtie
+  #       end
   #     end
-  #   end
-  # 
+  #
   # * Require your own gem as well as rails in this file:
-  # 
-  #   # lib/my_gem/railtie.rb
-  #   require 'my_gem'
-  #   require 'rails'
-  # 
-  #   module MyGem
-  #     class Railtie < Rails::Railtie
+  #
+  #     # lib/my_gem/railtie.rb
+  #     require 'my_gem'
+  #     require 'rails'
+  #     
+  #     module MyGem
+  #       class Railtie < Rails::Railtie
+  #       end
   #     end
-  #   end
   #
   # == Initializers
   #
@@ -65,7 +65,7 @@ module Rails
   #     end
   #   end
   #
-  # If specified, the block can also receive the application object, in case you 
+  # If specified, the block can also receive the application object, in case you
   # need to access some application specific configuration, like middleware:
   #
   #   class MyRailtie < Rails::Railtie