From e2a5cba7721e6a63c3d7b7706b3e0247d1a19a08 Mon Sep 17 00:00:00 2001
From: kay <kay.kim@10gen.com>
Date: Mon, 8 Apr 2013 10:59:43 -0400
Subject: [PATCH] DOCS-596 make drop by index name more explicit

---
 .../method/db.collection.dropIndex.txt        | 50 +++++++++++--------
 1 file changed, 29 insertions(+), 21 deletions(-)

diff --git a/source/reference/method/db.collection.dropIndex.txt b/source/reference/method/db.collection.dropIndex.txt
index b6dcf84a464..46f91fd53bb 100644
--- a/source/reference/method/db.collection.dropIndex.txt
+++ b/source/reference/method/db.collection.dropIndex.txt
@@ -10,22 +10,24 @@ db.collection.dropIndex()
    :method:`db.collection.dropIndex()` method provides a wrapper around
    the :dbcommand:`dropIndexes` command.
 
+   .. note::
+
+      The :method:`db.collection.dropIndex()` method cannot drop the
+      ``_id`` index.
+
    The :method:`db.collection.dropIndex()` method takes the following
    parameter:
 
    :param index:
+          Specifies the index to drop. You can specify the index either
+          by the index name or by the index specification document.
+          [#version-changed]_ See :ref:`document-index-specification`
+          for information on index specification documents. To view all
+          indexes on a collection, use the
+          :method:`db.collection.getIndexes()` method.
 
-          Specifies 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``:
+   The following example uses the :method:`db.collection.dropIndex()`
+   method on the collection ``pets`` that has the following indexes:
 
    .. code-block:: javascript
 
@@ -50,19 +52,25 @@ db.collection.dropIndex()
          }
       ]
 
-   - To drop the index on the field ``cat``, you must use the index
-     name ``catIdx``:
+   Consider the index on the field ``cat``. The index has the
+   user-specified name of ``catIdx`` [#index-name]_. To drop the index
+   ``catIdx``, you can use either the index name:
 
-     .. code-block:: javascript
+   .. code-block:: javascript
+
+      db.pets.dropIndex( "catIdx" )
 
-        db.pets.dropIndex( 'catIdx' )
+   or the index specification document ``{ "cat" : 1 }``:
 
-   - To drop the index on the fields ``cat`` and ``dog``, you use
-     either the index name ``cat_1_dog_-1`` or the key ``{ "cat" : 1,
-     "dog" : -1 }``:
+   .. code-block:: javascript
 
-     .. code-block:: javascript
+      db.pets.dropIndex( { "cat" : 1 } )
 
-        db.pets.dropIndex( 'cat_1_dog_-1' )
+   .. [#version-changed] When using a :program:`mongo` shell version
+      earlier than 2.2.2, if you specified a name during the index
+      creation, you must use the name to drop the index.
 
-        db.pets.dropIndex( { cat : 1, dog : -1 } )
+   .. [#index-name] During index creation, if the user does **not**
+      specify an index name, the system generates the name by
+      concatenating the index key field and value with an underscore,
+      e.g. ``cat_1``.