diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index 99dd50ccb1..f6321f1499 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -283,6 +283,38 @@ module ActiveRecord
   #
   # In application.rb.
   #
+  # == Reversible Migrations
+  #
+  # Starting with Rails 3.1, you will be able to define reversible migrations.
+  # Reversible migrations are migrations that know how to go +down+ for you.
+  # You simply supply the +up+ logic, and the Migration system will figure out
+  # how to execute the down commands for you.
+  #
+  # To define a reversible migration, define the +change+ method in your
+  # migration like this:
+  #
+  #   class TenderloveMigration < ActiveRecord::Migration
+  #     def change
+  #       create_table(:horses) do
+  #         t.column :content, :text
+  #         t.column :remind_at, :datetime
+  #       end
+  #     end
+  #   end
+  #
+  # This migration will create the horses table for you on the way up, and
+  # automatically figure out how to drop the table on the way down.
+  #
+  # Some commands like +remove_column+ cannot be reversed.  If you care to
+  # define how to move up and down in these cases, you should define the +up+
+  # and +down+ methods as before.
+  #
+  # If a command cannot be reversed, an
+  # <tt>ActiveRecord::IrreversibleMigration</tt> exception will be raised when
+  # the migration is moving down.
+  #
+  # For a list of commands that are reversible, please see
+  # <tt>ActiveRecord::Migration::CommandRecorder</tt>.
   class Migration
     autoload :CommandRecorder, 'active_record/migration/command_recorder'
 
diff --git a/activerecord/lib/active_record/migration/command_recorder.rb b/activerecord/lib/active_record/migration/command_recorder.rb
index fc669d2e89..d7e481905a 100644
--- a/activerecord/lib/active_record/migration/command_recorder.rb
+++ b/activerecord/lib/active_record/migration/command_recorder.rb
@@ -1,7 +1,17 @@
 module ActiveRecord
   class Migration
     # ActiveRecord::Migration::CommandRecorder records commands done during
-    # a migration and knows how to reverse those commands.
+    # a migration and knows how to reverse those commands.  The CommandRecorder
+    # knows how to invert the following commands:
+    #
+    # * add_column
+    # * add_index
+    # * add_timestamp
+    # * create_table
+    # * remove_timestamps
+    # * rename_column
+    # * rename_index
+    # * rename_table
     class CommandRecorder
       attr_accessor :commands, :delegate