DOCS-540 add dropTarget option to renameCollection

source/reference/command/renameCollection.txt

@@ -4,41 +4,75 @@ renameCollection
 
 .. default-domain:: mongodb
 
-.. dbcommand:: renameCollection
+.. dbcommand:: renameCollection( source-namespace, to: target-namespace [, dropTarget=>true])
 
-   The :dbcommand:`renameCollection` command changes the name of an existing
-   collection. Use the following form to rename the collection
-   named "things" to "events":
+   The :dbcommand:`renameCollection` command is an administrative command which
+   changes the name of an existing collection.
+   If the ``target-namespace`` specifies a collection in a different database, the
+   ``source-namespace`` collection will be copied to the new database and then dropped.
+   You must issue the
+   :dbcommand:`renameCollection`
+   command against the :term:`admin database` in the form:
 
    .. code-block:: javascript
 
-      { renameCollection: "store.things", to: "store.events" }
+      { renameCollection: <source-namespace>, to: <target-namespace> }
 
-   You must run this command against the admin database. and thus
-   requires you to specify the complete namespace (i.e., database name
-   and collection name.)
+   You must specify the complete :term:`namespace` (i.e., database name
+   and collection name).
+
+   :var source-namespace:
+
+      Specifies the complete namespace of the collection to be renamed.
+
+   :param string to: 
+
+      Specifies the new namespace of the collection.
+
+   :param boolean,optional dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection.
+
+   :exception 10026:
+
+      Raised if the ``source`` namespace does not exist.
+
+   :exception 10027:
+
+      Raised if the ``target`` namespace exists
+      and ``dropTarget`` is either ``false`` or unspecified.
+
+   :exception 15967:
+
+      Raised if the ``target`` namespace is an invalid collection name.   
 
-   .. note::
-
-      :dbcommand:`renameCollection` will not succeed if you have
-      existing data, or indexes, in the new collection.
+   You may safely use :dbcommand:`renameCollection` in production
+   environments.
 
-   The shell helper :method:`renameCollection()` provides a more
-   simple interface for this functionality. The following is
-   equivalent to the previous example:
+   .. warning::
 
-   .. code-block:: javascript
+      :dbcommand:`renameCollection` will fail if 
+      `target` is the name of an existing collection
+      and you do not specify ``dropTarget: true``.
+
+      You cannot use :dbcommand:`renameCollection` with
+      sharded collections.
+
+      If :dbcommand:`renameCollection` is interrupted prior to completion,
+      the ``target`` collection and indexes will be left in an inconsistent
+      state requiring manual intervention to clean up.
+
+      A copy of a database across collections will impact performance for
+      the duration of the copy.
+
+      You should not initiate :dbcommand:`renameCollection` while the 
+      source database is being written to. 
 
-      db.things.renameCollection( "events" )
+   The shell helper :method:`db.collection.renameCollection()` provides a
+   simpler interface to using this command within a database.
+   The following is equivalent to the previous example:
 
-   :dbcommand:`renameCollection` operates by changing the metadata
-   associated with a given collection. The duration of the command is
-   constant and not related to the size of the collection or the
-   indexes; however, the operation will invalidate open cursors which
-   will interrupt queries that are currently returning data.
+   .. code-block:: javascript
 
-   You may safely use :dbcommand:`renameCollection` in production
-   environments.
+      db.source-namespace.renameCollection( "target" )
+
+
 
-   .. warning:: You cannot use :dbcommand:`renameCollection` with
-      sharded collections.

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

@@ -6,8 +6,9 @@ db.collection.renameCollection()
 
 .. method:: db.collection.renameCollection()
 
-   :param string name: Specifies the new name of the
-                       collection. Enclose the string in quotes.
+   :param string target: Specifies the new name of the collection. Enclose the string in quotes.
+
+   :param boolean,optional dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection.
 
    Call the :method:`db.collection.renameCollection()` method on a collection
    object, to rename a collection. Specify the new name of the
@@ -20,9 +21,26 @@ db.collection.renameCollection()
    This method renames a collection named ``rrecord`` to
    ``record``. If the target name (i.e. ``record``) is the name of
    an existing collection, then the operation will fail.
+
+   The :method:`db.collection.renameCollection()` method cannot be 
+   used to move a collection across databases.
+
+   The :method:`db.collection.renameCollection()` method operates 
+   within a collection by changing the metadata associated with a 
+   given collection. 
 
    :method:`db.collection.renameCollection()` provides a wrapper around the
-   :term:`database command` ":dbcommand:`renameCollection`".
-
-   .. warning:: You cannot use :method:`renameCollection()
-      <db.collection.renameCollection()>` with sharded collections.
+   :term:`database command` ":dbcommand:`renameCollection`".  Please 
+   refer to :dbcommand:`renameCollection` for further warnings and
+   messages.
+
+   .. warning::
+
+      The :method:`db.collection.renameCollection()` method and
+      :dbcommand:`renameCollection` command will invalidate open 
+      cursors which will interrupt queries that are currently returning data.
+
+   .. warning:: 
+
+      You cannot use :method:`db.collection.renameCollection()` or
+      :dbcommand:`renameCollection` with sharded collections.