DOCS-596 dropIndex by name

Author: kay-kim

source/reference/method/db.collection.dropIndex.txt

@@ -4,13 +4,66 @@ db.collection.dropIndex()
 
 .. default-domain:: mongodb
 
-.. method:: db.collection.dropIndex(name)
+.. method:: db.collection.dropIndex(index)
 
-   :param name: The name of the index to drop.
+   Drops or removes the specified index from a collection. The
+   :method:`db.collection.dropIndex()` method provides a wrapper around
+   the :dbcommand:`dropIndexes` command.
+   
+   The :method:`db.collection.dropIndex()` method takes the following
+   parameters:
 
-   Drops or removes the specified index. This method provides a
-   wrapper around the :dbcommand:`dropIndexes`.
+   :param index: 
+   
+          Either the name or the key of the index to drop. You **must**
+          use the name of the index if you specified a name during the
+          index creation.
+   
+   The :method:`db.collection.dropIndex()` method cannot drop the
+   ``_id`` index. Use the :method:`db.collection.getIndexes()` method
+   to view all indexes on a collection.
+
+   Consider the following examples of the
+   :method:`db.collection.dropIndex()` method that assumes the
+   following indexes on the collection ``pets``:
+   
+   .. code-block:: javascript
+   
+      > db.pets.getIndexes()
+      [
+         {  "v" : 1,
+            "key" : { "_id" : 1 },
+            "ns" : "test.pets",
+            "name" : "_id_"
+         }, 
+         {
+            "v" : 1,
+            "key" : { "cat" : -1 }, 
+            "ns" : "test.pets",
+            "name" : "catIdx"
+         },
+         {
+            "v" : 1,
+            "key" : { "cat" : 1, "dog" : -1 },
+            "ns" : "test.pets",
+            "name" : "cat_1_dog_-1"
+         }
+      ]
+
+   - To drop the index on the field ``cat``, you must use the index
+     name ``catIdx``:
+     
+     .. code-block:: javascript
+   
+        db.pets.dropIndex( 'catIdx' )
+   
+   - To drop the index on the fields ``cat`` and ``dog``, you can use
+     either the index name ``cat_1_dog_-1`` or the key ``{ "cat" : 1,
+     "dog" : -1 }``:
+
+     .. code-block:: javascript
+
+        db.pets.dropIndex( 'cat_1_dog_-1' )
+
+        db.pets.dropIndex( { cat : 1, dog : -1 } )
 
-   Use :method:`db.collection.getIndexes()` to get a list of the indexes on the
-   current collection, and only call :method:`db.collection.dropIndex()` as a
-   method on a collection object.