Merge docrails

1 files changed, 36 insertions, 2 deletions

diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
index 75032efe57..22304edfc9 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
@@ -252,6 +252,10 @@ module ActiveRecord
     class IndexDefinition < Struct.new(:table, :name, :unique, :columns) #:nodoc:
     end
 
+    # Abstract representation of a column definition. Instances of this type
+    # are typically created by methods in TableDefinition, and added to the
+    # +columns+ attribute of said TableDefinition object, in order to be used
+    # for generating a number of table creation or table changing SQL statements.
     class ColumnDefinition < Struct.new(:base, :name, :type, :limit, :precision, :scale, :default, :null) #:nodoc:
 
       def sql_type
@@ -275,9 +279,29 @@ module ActiveRecord
         end
     end
 
-    # Represents a SQL table in an abstract way.
-    # Columns are stored as a ColumnDefinition in the +columns+ attribute.
+    # Represents the schema of an SQL table in an abstract way. This class
+    # provides methods for manipulating the schema representation.
+    #
+    # Inside migration files, the +t+ object in +create_table+ and
+    # +change_table+ is actually of this type:
+    #
+    #   class SomeMigration < ActiveRecord::Migration
+    #     def self.up
+    #       create_table :foo do |t|
+    #         puts t.class  # => "ActiveRecord::ConnectionAdapters::TableDefinition"
+    #       end
+    #     end
+    #     
+    #     def self.down
+    #       ...
+    #     end
+    #   end
+    #
+    # The table definitions
+    # The Columns are stored as a ColumnDefinition in the +columns+ attribute.
     class TableDefinition
+      # An array of ColumnDefinition objects, representing the column changes
+      # that have been defined.
       attr_accessor :columns
 
       def initialize(base)
@@ -321,6 +345,12 @@ module ActiveRecord
       # * <tt>:scale</tt> -
       #   Specifies the scale for a <tt>:decimal</tt> column.
       #
+      # For clarity's sake: the precision is the number of significant digits,
+      # while the scale is the number of digits that can be stored following
+      # the decimal point. For example, the number 123.45 has a precision of 5
+      # and a scale of 2. A decimal with a precision of 5 and a scale of 2 can
+      # range from -999.99 to 999.99.
+      #
       # Please be aware of different RDBMS implementations behavior with
       # <tt>:decimal</tt> columns:
       # * The SQL standard says the default scale should be 0, <tt>:scale</tt> <=
@@ -374,6 +404,10 @@ module ActiveRecord
       #  td.column(:huge_integer, :decimal, :precision => 30)
       #  # => huge_integer DECIMAL(30)
       #
+      #  # Defines a column with a database-specific type.
+      #  td.column(:foo, 'polygon')
+      #  # => foo polygon
+      #
       # == Short-hand examples
       #
       # Instead of calling +column+ directly, you can also work with the short-hand definitions for the default types.