Add documentation for add_index and remove_index. Closes #3600.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@3487 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

activerecord/CHANGELOG

 *SVN*
 
+* Add documentation for add_index and remove_index. #3600 [Manfred Stienstra <m.stienstra@fngtps.com>]
+
 * If the OCI library is not available, raise an exception indicating as much. #3593 [schoenm@earthlink.net]
 
 * Add explicit :order in finder tests as postgresql orders results differently by default. #3577. [Rick Olson]

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

@@ -153,6 +153,13 @@ def rename_column(table_name, column_name, new_column_name)
       # The index will be named after the table and the first column names,
       # unless you pass +:name+ as an option.
       #
+      # When creating an index on multiple columns, the first column is used as a name
+      # for the index. For example, when you specify an index on two columns
+      # [+:first+, +:last+], the DBMS creates an index for both columns as well as an
+      # index for the first colum +:first+. Using just the first name for this index
+      # makes sense, because you will never have to create a singular index with this
+      # name.
+      #
       # ===== Examples
       # ====== Creating a simple index
       #  add_index(:suppliers, :name)
@@ -187,7 +194,10 @@ def add_index(table_name, column_name, options = {})
       #   remove_index :accounts, :column => :branch_id
       # Remove the index named by_branch_party in the accounts table.
       #   remove_index :accounts, :name => :by_branch_party
-      
+      #
+      # You can remove an index on multiple columns by specifying the first column.
+      #   add_index :accounts, [:username, :password]
+      #   remove_index :accounts, :username
       def remove_index(table_name, options = {})
         execute "DROP INDEX #{index_name(table_name, options)} ON #{table_name}"
       end