DOCS-946: changing cloneCollection documentation to reflect actual behavior

Author: Sam Kleinman

source/core/document.txt

@@ -245,6 +245,8 @@ Consider the following options for the value of an ``_id`` field:
   information concerning UUID interoperability.
 
 .. _documents-query-selectors:
+.. _mongodb-query-documents:
+.. _mongodb-query-document:
 
 Query Specification Documents
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/reference/command/cloneCollection.txt

@@ -27,10 +27,10 @@ cloneCollection
 
    .. code-block:: javascript
 
-      { cloneCollection: "users", from: "db.example.net:27017", query: { active: true }, copyIndexes: false }
+      { cloneCollection: "users.profiles", from: "mongodb.example.net:27017", query: { active: true }, copyIndexes: false }
 
-   This operation copies the "users" collection from the current
-   database on the server at ``db.example.net``. The operation only
+   This operation copies the ``profiles`` collection from the
+   ``users`` database on the server at ``mongodb.example.net``. The operation only
    copies documents that satisfy the query ``{ active: true }`` and
    does not copy indexes. :dbcommand:`cloneCollection` copies indexes
    by default, but you can disable this behavior by setting ``{
@@ -39,6 +39,6 @@ cloneCollection
 
    :dbcommand:`cloneCollection` creates a collection on the current
    database with the same name as the origin collection. If, in the
-   above example, the ``users`` collection already exists, then
-   MongoDB appends documents in the remote collection to the
-   destination collection.
+   above example, the ``users`` collection already exists in the local
+   database, then MongoDB appends documents in the remote collection
+   to the destination collection.

source/reference/method/db.cloneCollection.txt

@@ -0,0 +1,30 @@
+====================
+db.cloneCollection()
+====================
+
+.. default-domain:: mongodb
+
+.. method:: db.cloneCollection(from, collection, query)
+
+   :method:`db.cloneCollection()` provides a wrapper around
+   :dbcommand:`cloneCollection` for copying data directly between
+   :MongoDB instances.
+
+   :param string from: A host name, of the MongoDB instance that holds
+                       the collection you wish to copy
+
+   :param string collection: A collection in the MongoDB instance that
+                             you want to
+                             copy. :method:`db.cloneCollection()` will
+                             only copy the collection with this name
+                             from *database* of the same name as the
+                             current database the remote MongoDB
+                             instance. If you want to copy a
+                             collection from a different database name
+                             you must use the
+                             :dbcommand:`cloneCollection` directly.
+
+   :param document query: Optional. A standard :ref:`MongoDB query
+                          document <mongodb-query-document>` to limit
+                          the documents copied as part of the
+                          :method:`db.cloneCollection()` operation.