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

Conflicts:
	railties/guides/source/contributing_to_ruby_on_rails.textile

8 files changed, 65 insertions, 24 deletions

diff --git a/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb b/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb
index b4db1eed18..6f21cea288 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb
@@ -113,7 +113,7 @@ module ActiveRecord
         end
       end
 
-      # A cached lookup for table existence
+      # A cached lookup for table existence.
       def table_exists?(name)
         return true if @tables.key? name
 
@@ -135,7 +135,7 @@ module ActiveRecord
         @tables.clear
       end
 
-      # Clear out internal caches for table with +table_name+
+      # Clear out internal caches for table with +table_name+.
       def clear_table_cache!(table_name)
         @columns.delete table_name
         @columns_hash.delete table_name
@@ -193,7 +193,7 @@ module ActiveRecord
         @connections = []
       end
 
-      # Clears the cache which maps classes
+      # Clears the cache which maps classes.
       def clear_reloadable_connections!
         @reserved_connections.each do |name, conn|
           checkin conn
@@ -365,7 +365,7 @@ module ActiveRecord
         @connection_pools.each_value {|pool| pool.release_connection }
       end
 
-      # Clears the cache which maps classes
+      # Clears the cache which maps classes.
       def clear_reloadable_connections!
         @connection_pools.each_value {|pool| pool.clear_reloadable_connections! }
       end
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb b/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb
index 29ac9341ec..30ccb8f0a4 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb
@@ -2,52 +2,53 @@ module ActiveRecord
   module ConnectionAdapters # :nodoc:
     module DatabaseLimits
 
-      # the maximum length of a table alias
+      # Returns the maximum length of a table alias.
       def table_alias_length
         255
       end
 
-      # the maximum length of a column name
+      # Returns the maximum length of a column name.
       def column_name_length
         64
       end
 
-      # the maximum length of a table name
+      # Returns the maximum length of a table name.
       def table_name_length
         64
       end
 
-      # the maximum length of an index name
+      # Returns the maximum length of an index name.
       def index_name_length
         64
       end
 
-      # the maximum number of columns per table
+      # Returns the maximum number of columns per table.
       def columns_per_table
         1024
       end
 
-      # the maximum number of indexes per table
+      # Returns the maximum number of indexes per table.
       def indexes_per_table
         16
       end
 
-      # the maximum number of columns in a multicolumn index
+      # Returns the maximum number of columns in a multicolumn index.
       def columns_per_multicolumn_index
         16
       end
 
-      # the maximum number of elements in an IN (x,y,z) clause. nil means no limit
+      # Returns the maximum number of elements in an IN (x,y,z) clause.
+      # nil means no limit.
       def in_clause_length
         nil
       end
 
-      # the maximum length of an SQL query
+      # Returns the maximum length of an SQL query.
       def sql_query_length
         1048575
       end
 
-      # maximum number of joins in a single query
+      # Returns maximum number of joins in a single query.
       def joins_per_query
         256
       end
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
index 8bae50885f..9f9c2c42cb 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -17,6 +17,10 @@ module ActiveRecord
 
       # def tables(name = nil) end
 
+      # Checks to see if the table +table_name+ exists on the database.
+      #
+      # === Example
+      #   table_exists?(:developers)
       def table_exists?(table_name)
         tables.include?(table_name.to_s)
       end
@@ -24,7 +28,7 @@ module ActiveRecord
       # Returns an array of indexes for the given table.
       # def indexes(table_name, name = nil) end
 
-      # Checks to see if an index exists on a table for a given index definition
+      # Checks to see if an index exists on a table for a given index definition.
       #
       # === Examples
       #  # Check an index exists
diff --git a/activerecord/lib/active_record/connection_adapters/mysql2_adapter.rb b/activerecord/lib/active_record/connection_adapters/mysql2_adapter.rb
index 8973544028..d3a054c29b 100644
--- a/activerecord/lib/active_record/connection_adapters/mysql2_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/mysql2_adapter.rb
@@ -132,6 +132,7 @@ module ActiveRecord
         ADAPTER_NAME
       end
 
+      # Returns true, since this connection adapter supports migrations.
       def supports_migrations?
         true
       end
@@ -140,6 +141,7 @@ module ActiveRecord
         true
       end
 
+      # Returns true, since this connection adapter supports savepoints.
       def supports_savepoints?
         true
       end
@@ -386,6 +388,10 @@ module ActiveRecord
         end
       end
 
+      # Drops a MySQL database.
+      #
+      # Example:
+      #   drop_database('sebastian_development')
       def drop_database(name) #:nodoc:
         execute "DROP DATABASE IF EXISTS `#{name}`"
       end
@@ -416,6 +422,7 @@ module ActiveRecord
         super(table_name, options)
       end
 
+      # Returns an array of indexes for the given table.
       def indexes(table_name, name = nil)
         indexes = []
         current_index = nil
@@ -433,6 +440,7 @@ module ActiveRecord
         indexes
       end
 
+      # Returns an array of +Mysql2Column+ objects for the table specified by +table_name+.
       def columns(table_name, name = nil)
         sql = "SHOW FIELDS FROM #{quote_table_name(table_name)}"
         columns = []
@@ -447,6 +455,10 @@ module ActiveRecord
         super(table_name, options.reverse_merge(:options => "ENGINE=InnoDB"))
       end
 
+      # Renames a table.
+      #
+      # Example:
+      #   rename_table('octopuses', 'octopi')
       def rename_table(table_name, new_name)
         execute "RENAME TABLE #{quote_table_name(table_name)} TO #{quote_table_name(new_name)}"
       end
@@ -531,6 +543,7 @@ module ActiveRecord
         variables.first['Value'] unless variables.empty?
       end
 
+      # Returns a table's primary key and belonging sequence.
       def pk_and_sequence_for(table)
         keys = []
         result = execute("describe #{quote_table_name(table)}")
diff --git a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
index 356aaf0ebe..862ce852e6 100644
--- a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
@@ -201,13 +201,13 @@ module ActiveRecord
         true
       end
 
-      # Returns +true+, since this connection adapter supports prepared statement
+      # Returns true, since this connection adapter supports prepared statement
       # caching.
       def supports_statement_cache?
         true
       end
 
-      # Returns true.
+      # Returns true, since this connection adapter supports migrations.
       def supports_migrations? #:nodoc:
         true
       end
@@ -217,6 +217,7 @@ module ActiveRecord
         true
       end
 
+      # Returns true, since this connection adapter supports savepoints.
       def supports_savepoints? #:nodoc:
         true
       end
@@ -584,6 +585,7 @@ module ActiveRecord
         super(table_name, options)
       end
 
+      # Returns an array of indexes for the given table.
       def indexes(table_name, name = nil)#:nodoc:
         indexes = []
         current_index = nil
@@ -602,6 +604,7 @@ module ActiveRecord
         indexes
       end
 
+      # Returns an array of +MysqlColumn+ objects for the table specified by +table_name+.
       def columns(table_name, name = nil)#:nodoc:
         sql = "SHOW FIELDS FROM #{quote_table_name(table_name)}"
         columns = []
@@ -615,6 +618,10 @@ module ActiveRecord
         super(table_name, options.reverse_merge(:options => "ENGINE=InnoDB"))
       end
 
+      # Renames a table.
+      #
+      # Example:
+      #   rename_table('octopuses', 'octopi')
       def rename_table(table_name, new_name)
         execute "RENAME TABLE #{quote_table_name(table_name)} TO #{quote_table_name(new_name)}"
       end
@@ -892,6 +899,7 @@ module ActiveRecord
           version[0] >= 5
         end
 
+        # Returns the version of the connected MySQL server.
         def version
           @version ||= @connection.server_info.scan(/^(\d+)\.(\d+)\.(\d+)/).flatten.map { |v| v.to_i }
         end
diff --git a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
index 3b0d960acc..37db2be7a9 100644
--- a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
@@ -294,7 +294,7 @@ module ActiveRecord
         NATIVE_DATABASE_TYPES
       end
 
-      # Does PostgreSQL support migrations?
+      # Returns true, since this connection adapter supports migrations.
       def supports_migrations?
         true
       end
@@ -320,6 +320,7 @@ module ActiveRecord
         true
       end
 
+      # Returns true, since this connection adapter supports savepoints.
       def supports_savepoints?
         true
       end
@@ -682,7 +683,7 @@ module ActiveRecord
         [schema, table]
       end
 
-      # Returns the list of all indexes for a table.
+      # Returns an array of indexes for the given table.
       def indexes(table_name, name = nil)
          schemas = schema_search_path.split(/,/).map { |p| quote(p) }.join(',')
          result = query(<<-SQL, name)
@@ -847,6 +848,9 @@ module ActiveRecord
       end
 
       # Renames a table.
+      #
+      # Example:
+      #   rename_table('octopuses', 'octopi')
       def rename_table(name, new_name)
         execute "ALTER TABLE #{quote_table_name(name)} RENAME TO #{quote_table_name(new_name)}"
       end
@@ -931,7 +935,7 @@ module ActiveRecord
       end
 
       protected
-        # Returns the version of the connected PostgreSQL version.
+        # Returns the version of the connected PostgreSQL server.
         def postgresql_version
           @connection.server_version
         end
diff --git a/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb b/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
index 04367657ec..d2785b234a 100644
--- a/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
@@ -58,10 +58,12 @@ module ActiveRecord
         'SQLite'
       end
 
+      # Returns true if SQLite version is '2.0.0' or greater, false otherwise.
       def supports_ddl_transactions?
         sqlite_version >= '2.0.0'
       end
 
+      # Returns true if SQLite version is '3.6.8' or greater, false otherwise.
       def supports_savepoints?
         sqlite_version >= '3.6.8'
       end
@@ -72,7 +74,7 @@ module ActiveRecord
         true
       end
 
-      # Returns true.
+      # Returns true, since this connection adapter supports migrations.
       def supports_migrations? #:nodoc:
         true
       end
@@ -86,6 +88,7 @@ module ActiveRecord
         true
       end
 
+      # Returns true if SQLite version is '3.1.6' or greater, false otherwise.
       def supports_add_column?
         sqlite_version >= '3.1.6'
       end
@@ -103,10 +106,12 @@ module ActiveRecord
         @statements.clear
       end
 
+      # Returns true if SQLite version is '3.2.6' or greater, false otherwise.
       def supports_count_distinct? #:nodoc:
         sqlite_version >= '3.2.6'
       end
 
+      # Returns true if SQLite version is '3.1.0' or greater, false otherwise.
       def supports_autoincrement? #:nodoc:
         sqlite_version >= '3.1.0'
       end
@@ -250,6 +255,7 @@ module ActiveRecord
         end
       end
 
+      # Returns an array of +SQLiteColumn+ objects for the table specified by +table_name+.
       def columns(table_name, name = nil) #:nodoc:
         table_structure(table_name).map do |field|
           case field["dflt_value"]
@@ -265,6 +271,7 @@ module ActiveRecord
         end
       end
 
+      # Returns an array of indexes for the given table.
       def indexes(table_name, name = nil) #:nodoc:
         exec_query("PRAGMA index_list(#{quote_table_name(table_name)})", name).map do |row|
           IndexDefinition.new(
@@ -288,6 +295,10 @@ module ActiveRecord
         exec_query "DROP INDEX #{quote_column_name(index_name)}"
       end
 
+      # Renames a table.
+      #
+      # Example:
+      #   rename_table('octopuses', 'octopi')
       def rename_table(name, new_name)
         exec_query "ALTER TABLE #{quote_table_name(name)} RENAME TO #{quote_table_name(new_name)}"
       end
diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb
index d73fce9fd0..de36dd20b3 100644
--- a/activerecord/lib/active_record/validations.rb
+++ b/activerecord/lib/active_record/validations.rb
@@ -30,7 +30,7 @@ module ActiveRecord
     include ActiveModel::Validations
 
     module ClassMethods
-      # Creates an object just like Base.create but calls save! instead of save
+      # Creates an object just like Base.create but calls <tt>save!</tt> instead of +save+
       # so an exception is raised if the record is invalid.
       def create!(attributes = nil, &block)
         if attributes.is_a?(Array)
@@ -44,13 +44,13 @@ module ActiveRecord
       end
     end
 
-    # The validation process on save can be skipped by passing :validate => false. The regular Base#save method is
+    # The validation process on save can be skipped by passing <tt>:validate => false</tt>. The regular Base#save method is
     # replaced with this when the validations module is mixed in, which it is by default.
     def save(options={})
       perform_validations(options) ? super : false
     end
 
-    # Attempts to save the record just like Base#save but will raise a RecordInvalid exception instead of returning false
+    # Attempts to save the record just like Base#save but will raise a +RecordInvalid+ exception instead of returning false
     # if the record is not valid.
     def save!(options={})
       perform_validations(options) ? super : raise(RecordInvalid.new(self))