Update MongoDB\Collection documentation

docs/includes/apiargs-MongoDBCollection-method-aggregate-option.yaml

@@ -2,9 +2,9 @@ arg_name: option
 name: allowDiskUse
 type: boolean
 description: |
-  Enables writing to temporary files. When set to true, aggregation
-  stages can write data to the ``_tmp`` sub-directory in the dbPath
-  directory. The default is ``false``.
+  Enables writing to temporary files. When set to ``true``, aggregation stages
+  can write data to the ``_tmp`` sub-directory in the dbPath directory.
+  The default is ``false``.
 interface: phpmethod
 operation: MongoDB\\Collection::aggregate
 optional: true
@@ -21,51 +21,61 @@ optional: true
 position: 2
 ---
 source:
-  ref: bypassDocumentValidation
   file: apiargs-common-option.yaml
+  ref: bypassDocumentValidation
 operation: MongoDB\\Collection::aggregate
-position: 5
+position: 3
 ---
 source:
-  ref: maxTimeMS
   file: apiargs-common-option.yaml
+  ref: maxTimeMS
 operation: MongoDB\\Collection::aggregate
 position: 4
 ---
 source:
-  ref: readConcern
   file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::selectDatabase
+  ref: readConcern
+operation: MongoDB\\Collection::aggregate
+position: 5
 replacement:
   resource: "aggregation"
-position: 5
+  parent: "collection"
 ---
 source:
-  ref: readPreference
   file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::selectDatabase
+  ref: readPreference
+operation: MongoDB\\Collection::aggregate
+position: 6
 replacement:
   resource: "aggregation"
-position: 6
+  parent: "collection"
 ---
 source:
-  ref: typeMap
   file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::selectDatabase
+  ref: typeMap
+operation: MongoDB\\Collection::aggregate
 position: 7
+description: |
+  Type map for BSON deserialization. This will be applied to the returned
+  cursor. Defaults to the collections's type map.
+
+  .. note::
+
+     This is not supported for inline aggregation results (i.e. ``useCursor``
+     option is ``false`` or the server version is < 2.6).
 ---
 arg_name: param
 name: useCursor
 type: boolean
 description: |
-  Indicates whether the command will request that the server provide
-  results using a cursor. The default is ``true``.
+  Indicates whether the command will request that the server provide results
+  using a cursor. The default is ``true``.
 
-  For MongoDB version 2.6 or later, ``useCursor`` allows users to turn
-  off cursors if necessary to aid in mongod/mongos upgrades.
+  For MongoDB version 2.6 or later, ``useCursor`` allows users to turn off
+  cursors if necessary to aid in replica set or shard cluster upgrades.
 
-  ``useCursor`` is ignored for MongoDB versions prior to 2.6 as
-  aggregation cursors are not available pre-2.6.
+  ``useCursor`` is ignored for MongoDB versions prior to 2.6 as aggregation
+  cursors are not available.
 interface: phpmethod
 operation: MongoDB\\Collection::aggregate
 optional: true

docs/includes/apiargs-MongoDBCollection-method-aggregate-param.yaml

@@ -2,15 +2,15 @@ arg_name: param
 name: $pipeline
 type: array
 description: |
-  Specifies an :manual:`aggregation pipeline </core/aggregation-pipeline>` operation.
+  Specifies an :manual:`aggregation pipeline </core/aggregation-pipeline>`
+  operation.
 interface: phpmethod
 operation: MongoDB\\Collection::aggregate
-optional: true
 position: 1
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
+  ref: $options
 operation: MongoDB\\Collection::aggregate
 position: 2
 ...

docs/includes/apiargs-MongoDBCollection-method-bulkWrite-option.yaml

 source:
-  ref: bypassDocumentValidation
   file: apiargs-common-option.yaml
+  ref: bypassDocumentValidation
 operation: MongoDB\\Collection::bulkWrite
 position: 1
 ---
@@ -8,23 +8,24 @@ arg_name: option
 name: ordered
 type: boolean
 description: |
-  If ``true``: when an insert fails, the operation returns without performing the
-  remaining writes. 
+  If ``true``: when a single write fails, the operation returns without
+  performing the remaining writes.
 
-  If ``false``: when a write fails, the operation will continue with the
+  If ``false``: when a single write fails, the operation will continue with the
   remaining writes, if any.
 
   The default is ``true``.
-optional: true
 interface: phpmethod
 operation: MongoDB\\Collection::bulkWrite
+optional: true
 position: 2
 ---
 source:
-  ref: writeConcern
   file: apiargs-common-option.yaml
+  ref: writeConcern
 operation: MongoDB\\Collection::bulkWrite
 replacement:
   resource: "write"
+  parent: "collection"
 position: 3
 ...

docs/includes/apiargs-MongoDBCollection-method-bulkWrite-param.yaml

@@ -2,14 +2,15 @@ arg_name: param
 name: $operations
 type: array
 description: |
-  An array containing the write operations to perform. {{role}}
-  supports :phpmethod:`deleteMany <MongoDB\\Collection::deleteMany>`,
-  :phpmethod:`deleteOne <MongoDB\\Collection::deleteOne>`, :phpmethod:`insertOne
-  <MongoDB\\Collection::insertOne>`, :phpmethod:`replaceOne
-  <MongoDB\\Collection::replaceOne>`, :phpmethod:`updateMany
-  <MongoDB\\Collection::updateMany>`, and :phpmethod:`updateOne
-  <MongoDB\\Collection::updateOne>` operations in the following array
-  structure:
+  An array containing the write operations to perform.
+  :phpmethod:`MongoDB\\Collection::bulkWrite()` supports
+  :phpmethod:`deleteMany() <MongoDB\\Collection::deleteMany>`,
+  :phpmethod:`deleteOne() <MongoDB\\Collection::deleteOne>`,
+  :phpmethod:`insertOne() <MongoDB\\Collection::insertOne>`,
+  :phpmethod:`replaceOne() <MongoDB\\Collection::replaceOne>`,
+  :phpmethod:`updateMany() <MongoDB\\Collection::updateMany>`, and
+  :phpmethod:`updateOne() <MongoDB\\Collection::updateOne>` operations in the
+  following array structure:
 
   .. code-block:: php
 
@@ -22,17 +23,18 @@ description: |
          [ 'updateOne'  => [ $filter, $update, $options ] ],
      ]
 post: |
-  Arguments correspond to the respective operation methods. However,
-  the ``writeConcern`` option is specified for the top-level bulk write
-  operation instead of each individual operation.
+  Arguments correspond to the respective operation methods. However, the
+  ``writeConcern`` option is specified as a top-level option to
+  :phpmethod:`MongoDB\\Collection::bulkWrite()` instead of each individual
+  operation.
 interface: phpmethod
 operation: MongoDB\\Collection::bulkWrite
 optional: true
 position: 1
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
+  ref: $options
 operation: MongoDB\\Collection::bulkWrite
 interface: phpmethod
 position: 2

docs/includes/apiargs-MongoDBCollection-method-construct-option.yaml

+source:
+  file: apiargs-common-option.yaml
+  ref: readConcern
+operation: MongoDB\\Collection::__construct
+position: 1
+replacement:
+  resource: "collection"
+  parent: "manager"
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: readPreference
+operation: MongoDB\\Collection::__construct
+position: 2
+replacement:
+  resource: "collection"
+  parent: "manager"
+---
+arg_name: option
+name: typeMap
+type: array
+description: |
+  Default :php:`type map
+  <manual/en/mongodb.persistence.deserialization.php#mongodb.persistence.typemaps>`
+  to apply to cursors. The type map determines how BSON documents are converted
+  to PHP values which determines. The |php-library| uses the following type map
+  by default:
+
+  .. code-block:: php
+
+     [
+         'array' => 'MongoDB\Model\BSONArray',
+         'document' => 'MongoDB\Model\BSONDocument',
+         'root' => 'MongoDB\Model\BSONDocument',
+     ]
+interface: phpmethod
+operation: MongoDB\\Collection::__construct
+optional: true
+position: 3
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: writeConcern
+operation: MongoDB\\Collection::__construct
+position: 4
+replacement:
+  resource: "collection"
+  parent: "manager"
+...

docs/includes/apiargs-MongoDBCollection-method-construct-param.yaml

-arg_name: param
-name: $manager
-type: :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>`
-description: |
-  The :php:`Manager <mongodb-driver-manager>` instance from the driver.
-  The manager maintains connections between the driver and your MongoDB
-  instances.
-interface: phpmethod
+source:
+  file: apiargs-common-param.yaml
+  ref: $manager
 operation: MongoDB\\Collection::__construct
-optional: false
 position: 1
 ---
 source:
-  ref: $databaseName
   file: apiargs-common-param.yaml
+  ref: $databaseName
 operation: MongoDB\\Collection::__construct
-replacement:
-  select: ""
 position: 2
 ---
 source:
-  ref: $collectionName
   file: apiargs-common-param.yaml
+  ref: $collectionName
 operation: MongoDB\\Collection::__construct
-replacement:
-  select: ""
 position: 3
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
+  ref: $options
 operation: MongoDB\\Collection::__construct
 position: 4
 ...

docs/includes/apiargs-MongoDBCollection-method-count-option.yaml

 arg_name: option
 name: hint
-type: string or array|object
+type: string|array|object
 description: |
-  The index to use. If you specify a document, it is interpreted as
-  an index specification and a name will be generated.
-optional: true
+  The index to use. If you specify a document, it is interpreted as an index
+  specification and a name will be generated.
 interface: phpmethod
 operation: MongoDB\\Collection::count
+optional: true
 position: 1
 ---
 arg_name: option
@@ -14,14 +14,14 @@ name: limit
 type: integer
 description: |
   The maximum number of documents to return.
-optional: true
 interface: phpmethod
 operation: MongoDB\\Collection::count
+optional: true
 position: 2
 ---
 source:
-  ref: maxTimeMS
   file: apiargs-common-option.yaml
+  ref: maxTimeMS
 operation: MongoDB\\Collection::count
 position: 3
 ---
@@ -31,6 +31,7 @@ source:
 operation: MongoDB\\Collection::count
 replacement:
   resource: "count"
+  parent: "collection"
 position: 4
 ---
 source:
@@ -38,6 +39,7 @@ source:
   file: apiargs-common-option.yaml
 replacement:
   resource: "count"
+  parent: "collection"
 position: 5
 ---
 arg_name: option
@@ -45,8 +47,8 @@ name: skip
 type: integer
 description: |
   The number of documents to skip before returning the documents.
-optional: true
 interface: phpmethod
 operation: MongoDB\\Collection::count
+optional: true
 position: 6
 ...

docs/includes/apiargs-MongoDBCollection-method-count-param.yaml

 source:
-  ref: $filter
   file: apiargs-common-param.yaml
+  ref: $filter
 operation: MongoDB\\Collection::count
 position: 1
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
+  ref: $options
 operation: MongoDB\\Collection::count
 position: 2
 ...

docs/includes/apiargs-MongoDBCollection-method-createIndex-option.yaml

@@ -42,8 +42,8 @@ arg_name: option
 name: name
 type: string
 description: |
-  Specifies the name for the index. By default, MongoDB creates index
-  names based on the key.
+  Specifies the name for the index. By default, MongoDB creates index names
+  based on the key.
 interface: phpmethod
 operation: MongoDB\\Collection::createIndex
 optional: true
@@ -64,36 +64,20 @@ arg_name: option
 name: 2dsphereIndexVersion
 type: integer
 description: |
-  Specifies the :manual:`version of a 2dsphere </core/2dsphere>` index
-  to create.
+  Specifies the :manual:`version of a 2dsphere </core/2dsphere>` index to
+  create.
 
-  MongoDB 2.6 introduced version 2 of 2dsphere indexes. Version 2 is
-  the default version of 2dsphere indexes created in MongoDB 2.6 and
-  later series. ``2dsphereIndexVersion`` enables you to overrride the
-  default version 2.
+  MongoDB 2.6 introduced version 2 of 2dsphere indexes. Version 2 is the default
+  version of 2dsphere indexes created in MongoDB 2.6 and later versions.
+  ``2dsphereIndexVersion`` enables you to overrride the default version 2.
 interface: phpmethod
 operation: MongoDB\\Collection::createIndex
 optional: true
 position: 7
 ---
-arg_name: option
-name: socketTimeoutMS
-type: integer
-description: |
-  Specifies the time limit, in milliseconds, for socket
-  communication. If the :program:`mongod` does not respond within the
-  timeout period, a ``MongoCursorTimeoutException`` is thrown and
-  there will be no way to determine if the server actually handled the
-  write or not. Specify ``-1`` to block indefinitely. The default value
-  is 30000 (30 seconds).
-interface: phpmethod
-operation: MongoDB\\Collection::createIndex
-optional: true
-position: 8
----
 source:
   ref: maxTimeMS
   file: apiargs-common-option.yaml
 operation: MongoDB\\Collection::createIndex
-position: 9
+position: 8
 ...

docs/includes/apiargs-MongoDBCollection-method-createIndex-param.yaml

@@ -4,13 +4,12 @@ type: array|object
 description: |
   Specifies the field or fields to index and the index order.
 
-  For example, the following specifies a descending index
-  on the ``username`` field:
+  For example, the following specifies a descending index on the ``username``
+  field:
 
   .. code-block:: php
 
-     $key = [ 'username' => -1 ];
-
+     [ 'username' => -1 ]
 operation: MongoDB\\Collection::createIndex
 interface: phpmethod
 optional: false

docs/includes/apiargs-MongoDBCollection-method-find-option.yaml

@@ -74,12 +74,11 @@ arg_name: option
 name: cursorType
 type: integer
 description: |
-  Indicates the type of cursor to use. The cursor types are
-  ``MongoDB\Operation\Find`` class constants. 
+   Indicates the type of cursor to use. ``cursorType`` supports the following
+   values:
 
-  Must be either
-  ``NON_TAILABLE``, ``TAILABLE``, or ``TAILABLE_AWAIT``. The default is
-  ``NON_TAILABLE``.
+   - ``MongoDB\Operation\Find::NON_TAILABLE`` (*default*)
+   - ``MongoDB\Operation\Find::TAILABLE``
 interface: phpmethod
 operation: MongoDB\\Collection::find
 optional: true

docs/includes/apiargs-MongoDBCollection-method-findOneAndReplace-option.yaml

@@ -22,10 +22,18 @@ source:
 operation: MongoDB\\Collection::findOneAndReplace
 position: 4
 ---
-source:
-  file: apiargs-MongoDBCollection-method-findOneAndUpdate-option.yaml
-  ref: returnDocument
-operation: MongoDB\\Collection::findOneAndReplace
+arg_name: option
+name: returnDocument
+type: integer
+description: |
+  Specifies whether to return the document before the replacementi applied, or
+  after. ``returnDocument`` supports the following values:
+
+  - ``MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_BEFORE`` (*default*)
+  - ``MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER``
+interface: phpmethod
+operation: MongoDB\Collection::findOneAndUpdate
+optional: true
 position: 5
 ---
 source:

docs/includes/apiargs-MongoDBCollection-method-findOneAndUpdate-option.yaml

@@ -26,16 +26,14 @@ arg_name: option
 name: returnDocument
 type: integer
 description: |
-  Specifies whether to return the document before the {{event}}, or
+  Specifies whether to return the document before the update is applied, or
   after. ``returnDocument`` supports the following values:
 
-  - ``MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_BEFORE`` (*default*)
-  - ``MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER``
-optional: true
-replacement:
-  event: "update is applied"
+  - ``MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_BEFORE`` (*default*)
+  - ``MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER``
 interface: phpmethod
 operation: MongoDB\Collection::findOneAndUpdate
+optional: true
 position: 5
 ---
 source:

docs/includes/apiargs-common-param.yaml

@@ -15,7 +15,7 @@ type: string
 description: |
   The name of the database{{action}}.
 interface: phpmethod
-operation: selectCollection
+operation: ~
 optional: false
 replacement:
   action: ""
@@ -27,7 +27,7 @@ type: string
 description: |
   The name of the collection{{action}}.
 interface: phpmethod
-operation: selectCollection
+operation: ~
 optional: false
 replacement:
   action: ""
@@ -39,7 +39,7 @@ type: array
 description: |
   An array specifying the desired options.
 interface: phpmethod
-operation: selectCollection
+operation: ~
 optional: true
 position: 3
 ---
@@ -49,7 +49,7 @@ type: array|object
 description: |
   The filter criteria that specifies the documents to {{verb}}.
 interface: phpmethod
-operation: count
+operation: ~
 optional: false
 position: 4
 replacement:

docs/includes/example-insertOne.rst

-.. code-block:: php
-                
-   <?php
-   
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('users','restaurants');
-
-   $newUser = $collection->insertOne(
-       [
-           'username' => 'admin',
-           'email' => 'admin@example.com',
-           'name' => 'Anna Bennett'
-       ],
-   );
-
-   echo "<pre>";
-   var_dump($newUser);
-
-The output would resemble:
-
-.. code-block:: none
-                
-   object(MongoDB\InsertOneResult)#13 (3) {
-     ["writeResult":"MongoDB\InsertOneResult":private]=>
-     object(MongoDB\Driver\WriteResult)#12 (9) {
-       ["nInserted"]=>
-       int(1)
-       ["nMatched"]=>
-       int(0)
-       ["nModified"]=>
-       int(0)
-       ["nRemoved"]=>
-       int(0)
-       ["nUpserted"]=>
-       int(0)
-       ["upsertedIds"]=>
-       array(0) {
-       }
-       ["writeErrors"]=>
-       array(0) {
-       }
-       ["writeConcernError"]=>
-       NULL
-       ["writeConcern"]=>
-       array(4) {
-         ["w"]=>
-         NULL
-         ["wmajority"]=>
-         bool(false)
-         ["wtimeout"]=>
-         int(0)
-         ["journal"]=>
-         NULL
-       }
-     }
-     ["insertedId":"MongoDB\InsertOneResult":private]=>
-     object(MongoDB\BSON\ObjectID)#11 (1) {
-       ["oid"]=>
-       string(24) "577282631f417d1823121691"
-     }
-     ["isAcknowledged":"MongoDB\InsertOneResult":private]=>
-     bool(true)
-   }
\ No newline at end of file

docs/includes/extracts-bson-deserialization-base.yaml

@@ -2,9 +2,8 @@ ref: _bson-deserialization
 content: |
   .. note::
 
-      {{method}} does not
-      yet support a ``typeMap`` option for BSON deserialization of the
-      returned document. 
+      {{method}} does not yet support a ``typeMap`` option for BSON
+      deserialization of the returned document.
 
       Classes implementing
       :php:`MongoDB\\BSON\\Persistable <class.mongodb-bson-persistable>`

docs/includes/extracts-bson-deserialization.yaml

@@ -3,19 +3,19 @@ source:
   file: extracts-bson-deserialization-base.yaml
   ref: _bson-deserialization
 replacement:
-  method: ":phpmethod:`MongoDB\\Collection::findOneAndDelete`"
+  method: ":phpmethod:`MongoDB\\Collection::findOneAndDelete()`"
 ---
 ref: bson-deserialization-findOneAndReplace
 source:
   file: extracts-bson-deserialization-base.yaml
   ref: _bson-deserialization
 replacement:
-  method: ":phpmethod:`MongoDB\\Collection::findOneAndReplace`"
+  method: ":phpmethod:`MongoDB\\Collection::findOneAndReplace()`"
 ---
 ref: bson-deserialization-findOneAndUpdate
 source:
   file: extracts-bson-deserialization-base.yaml
   ref: _bson-deserialization
 replacement:
-  method: ":phpmethod:`MongoDB\\Collection::findOneAndUpdate`"
+  method: ":phpmethod:`MongoDB\\Collection::findOneAndUpdate()`"
 ...

docs/reference/method/MongoDBCollection-aggregate.txt

@@ -13,7 +13,7 @@ MongoDB\\Collection::aggregate()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::aggregate($pipeline, $options)
+.. phpmethod:: MongoDB\\Collection::aggregate()
 
    Executes an :manual:`aggregation framework pipeline
    </core/aggregation-pipeline/>` operation on the collection.
@@ -22,45 +22,46 @@ Definition
 
       function aggregate(array $pipeline, array $options = []): Traversable
 
-   :phpmethod:`MongoDB\\Collection::aggregate` has the following
-   parameters:
+   :phpmethod:`MongoDB\\Collection::aggregate()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-aggregate-param.rst
 
-   :phpmethod:`MongoDB\\Collection::aggregate` supports the following
-   options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-aggregate-option.rst
 
-.. _php-agg-method-output:
+   :returns:
 
-Output
-------
+      A :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>` or
+      :php:`ArrayIterator <arrayiterator>` object. In both cases, the return
+      value will be :php:`Traversable <traversable>`.
 
-:phpmethod:`MongoDB\\Collection::aggregate`'s return value depends on
-the MongoDB server version and whether the ``useCursor`` option is
-specified. If ``useCursor`` is true,
-:phpmethod:`MongoDB\\Collection::aggregate` returns a
-``MongoDB\Driver\Cursor`` object. If ``useCursor`` is false,
-:phpmethod:`MongoDB\\Collection::aggregate` returns an
-``ArrayIterator`` that wraps the ``result`` array from the command
-response document.
+.. _php-agg-method-behavior:
+
+Behavior
+--------
+
+:phpmethod:`MongoDB\\Collection::aggregate()`'s return value depends on the
+MongoDB server version and whether the ``useCursor`` option is specified. If
+``useCursor`` is ``true``, a :php:`MongoDB\\Driver\\Cursor
+<class.mongodb-driver-cursor>` object is returned. If ``useCursor`` is
+``false``, an :php:`ArrayIterator <arrayiterator>` is returned that wraps the
+``result`` array from the command response document. In both cases, the return
+value will be :php:`Traversable <traversable>`.
 
 .. note::
 
-   BSON deserialization of inline aggregation results (i.e. not using a
-   command cursor) does not yet support a ``typeMap`` option. Classes
-   implementing :php:`MongoDB\\BSON\\Persistable
-   <mongodb-bson-persistable>` will still be deserialized according to
-   the :php:`Persistence <mongodb.persistence.deserialization>`
-   specification.
+   BSON deserialization of inline aggregation results (i.e. not using a command
+   cursor) does not yet support a ``typeMap`` option. Classes implementing
+   :php:`MongoDB\\BSON\\Persistable <mongodb-bson-persistable>` will still be
+   deserialized according to the
+   :php:`Persistence <mongodb.persistence.deserialization>` specification.
 
 .. todo: add examples
 
 .. seealso::
 
-   - :manual:`aggregate command reference
-     </reference/command/aggregate>` in the MongoDB manual and
-
+   - :manual:`aggregate </reference/command/aggregate>` command reference in the
+     MongoDB manual
    - :manual:`Aggregation Pipeline </core/aggregation-pipeline>`
-     documentation in the MongoDB Manual.
+     documentation in the MongoDB Manual

docs/reference/method/MongoDBCollection-bulkWrite.txt

@@ -13,7 +13,7 @@ MongoDB\\Collection::bulkWrite()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::bulkWrite($operations, $options)
+.. phpmethod:: MongoDB\\Collection::bulkWrite()
 
    Executes multiple write operations.
 
@@ -21,24 +21,29 @@ Definition
 
       function bulkWrite(array $operations, array $options = []): MongoDB\BulkWriteResult
 
-   :phpmethod:`MongoDB\\Collection::bulkWrite` has the following
-   parameters:
+   :phpmethod:`MongoDB\\Collection::bulkWrite()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-bulkWrite-param.rst
 
-   :phpmethod:`MongoDB\\Collection::bulkWrite` supports the following
-   options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-bulkWrite-option.rst
 
+   :returns:
+
+      A :phpclass:`MongoDB\\BulkWriteResult` object, which encapsulates a
+      :php:`MongoDB\\Driver\\WriteResult <class.mongodb-driver-writeresult>`
+      object.
+
 .. todo: add output and examples
 
 .. seealso::
 
-   - :phpmethod:`deleteMany <MongoDB\\Collection::deleteMany>`
-   - :phpmethod:`deleteOne <MongoDB\\Collection::deleteOne>` 
-   - :phpmethod:`insertOne <MongoDB\\Collection::insertOne>`
-   - :phpmethod:`replaceOne <MongoDB\\Collection::replaceOne>`
-   - :phpmethod:`updateMany <MongoDB\\Collection::updateMany>`
-   - :phpmethod:`updateOne <MongoDB\\Collection::updateOne>`
+   - :phpmethod:`MongoDB\\Collection::deleteMany()`
+   - :phpmethod:`MongoDB\\Collection::deleteOne()`
+   - :phpmethod:`MongoDB\\Collection::insertMany()`
+   - :phpmethod:`MongoDB\\Collection::insertOne()`
+   - :phpmethod:`MongoDB\\Collection::replaceOne()`
+   - :phpmethod:`MongoDB\\Collection::updateMany()`
+   - :phpmethod:`MongoDB\\Collection::updateOne()`
    - :doc:`/tutorial/crud`

docs/reference/method/MongoDBCollection-count.txt

@@ -13,27 +13,29 @@ MongoDB\\Collection::count()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::count($filter, $options)
+.. phpmethod:: MongoDB\\Collection::count()
 
-   Counts the number of documents that match filter criteria.
+   Count the number of documents that match the filter criteria.
 
    .. code-block:: php
 
       function count($filter = [], array $options = []): integer
 
-   :phpmethod:`MongoDB\\Collection::count` has the following
-   parameters:
+   :phpmethod:`MongoDB\\Collection::count()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-count-param.rst
 
-   :phpmethod:`MongoDB\\Collection::count` supports the following
-   options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-count-option.rst
 
+   :returns:
+
+      The number of documents matching the filter criteria.
+
 .. todo: add output and examples
 
 .. seealso::
 
-   - :manual:`count command reference </reference/command/count>`
-     in the MongoDB manual.
+   - :manual:`count </reference/command/count>` command reference in the MongoDB
+     manual

docs/reference/method/MongoDBCollection-createIndex.txt

@@ -13,7 +13,7 @@ MongoDBCollection::createIndex()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::createIndex($key, $options)
+.. phpmethod:: MongoDB\\Collection::createIndex()
 
    Create an index for the collection.
 
@@ -21,23 +21,22 @@ Definition
 
       function createIndex($key, array $options = []): string
 
-   ``createIndex()`` accepts the following parameters:
+   :phpmethod:`MongoDB\\Collection::createIndex()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-createIndex-param.rst
 
-   The ``$options`` parameter accepts all index options that your
-   MongoDB version supports. MongoDB 3.2 includes the following options:
+   The ``$options`` parameter accepts all index options that your MongoDB
+   version supports. MongoDB 3.2 includes the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-createIndex-option.rst
 
-   For a full list of the supported index creation options, refer to
-   the :manual:`createIndexes </reference/command/createIndexes>`
-   command reference in the MongoDB manual.
+   For a full list of the supported index creation options, refer to the
+   :manual:`createIndexes </reference/command/createIndexes>` command reference
+   in the MongoDB manual.
 
-Output
-------
+   :returns:
 
-Returns the name of the created index as a string.
+      The name of the created index as a string.
 
 Examples
 --------
@@ -45,63 +44,57 @@ Examples
 Create a Compound Index
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-The following operation creates a :manual:`compound index
-</core/index-compound>` on the ``borough`` and ``cuisine`` fields
-in the ``restaurants`` collection.
+The following example creates a :manual:`compound index </core/index-compound>`
+on the ``borough`` and ``cuisine`` fields in the ``restaurants`` collection in
+the ``example`` database.
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
+   $collection = (new MongoDB\Client)->selectCollection('example', 'restaurants');
 
-   $collection = $database->selectCollection('example','restaurants');
+   $indexName = $collection->createIndex(['borough' => 1, 'cuisine' => 1]);
 
-   $keys = ['borough' => 1, 'cuisine' => 1];
+   var_dump($indexName);
 
-   $indexString = $collection->createIndex($keys, ['name' => 'compound']);
+The output would then resemble::
 
-   var_dump($indexString);
-
-The output would resemble the following:
-
-.. code-block:: none
-                
-   string(8) "compound"
+   string(19) "borough_1_cuisine_1"
 
 Create a Partial Index
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The following operation adds a :manual:`partial index
-</core/index-parital>` on the ``borough`` field in the ``restaurants``
-collection in the ``example`` database. The partial index indexes only
-fields where the ``borough`` field exists.
+The following example adds a :manual:`partial index </core/index-parital>` on
+the ``borough`` field in the ``restaurants`` collection in the ``example``
+database. The partial index indexes only documents where the ``borough`` field
+exists.
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->selectCollection('example, 'restaurants');
 
-   $indexString = $collection->createIndex(
+   $indexName = $collection->createIndex(
       ['borough' => 1],
-      ['partialFilterExpression'=>
-         ['borough'=>
-            ['$exists'=>true]
-   ]]);
+      [
+          'partialFilterExpression' => [
+              'borough' => ['$exists' => true],
+          ],
+      ]
+   );
 
-   var_dump($indexString);
+   var_dump($indexName);
 
-The output would resemble::
+The output would then resemble::
 
    string(9) "borough_1"
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::createIndexes`
+   - :phpmethod:`MongoDB\\Collection::createIndexes()`
    - :doc:`/tutorial/indexes`
-   - :manual:`createIndexes </reference/command/createIndexes>` 
-     command reference in the MongoDB manual
-   - :manual:`Index documentation </indexes>`
+   - :manual:`createIndexes </reference/command/createIndexes>` command
+     reference in the MongoDB manual
+   - :manual:`Index </indexes>` documentation in the MongoDB Manual

docs/reference/method/MongoDBCollection-createIndexes.txt

@@ -21,66 +21,57 @@ Definition
 
       function createIndexes(array $indexes): string[]
 
-   ``createIndex()`` has one parameter: ``$indexes``, which is an array
-   or object.
-   Each element in the ``$indexes`` array|object must have a
-   "``key`` document" that specifies the fields to index and the
-   array direction or type. You can then specify index options as
-   additional key-value pairs in that element.
+   ``createIndex()`` has one parameter, ``$indexes``, which is an array. Each
+   element in ``$indexes`` must itself be an array that specifies an index. The
+   specification array requires a ``key`` field, which corresponds to the
+   ``$key`` parameter of :phpmethod:`MongoDB\\Collection::createIndex()`, and
+   may have other fields that correspond to options of
+   :phpmethod:`MongoDB\\Collection::createIndex()`.
 
-   For example, the following ``$indexes`` parameter creates an ascending
-   unique index on the ``username`` field:
+   For example, the following ``$indexes`` parameter creates two indexes. The
+   first is an ascending unique index on the ``username`` field and the second
+   is a 2dsphere index on the ``loc`` field with a custom name::
 
-   .. code-block:: none
-                   
-      [ 'key' => ['username => 1 '], 'unique' => true ],
-   
-   The following ``$indexes`` parameter creates a 2dsphere index on the ``loc`` field and
-   specifies a custom index name:
-   
-   .. code-block:: none
-                   
-      [ 'key' => [ 'loc' => '2dsphere'], 'name' => 'geo_index' ],
+      [
+          [ 'key' => [ 'username' => 1 ], 'unique' => true ],
+          [ 'key' => [ 'loc' => '2dsphere' ], 'name' => 'geo_index' ],
+      ]
 
    You can specify any index options that your MongoDB version
    supports. MongoDB 3.2 includes the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-createIndex-option.rst
 
-   For a full list of the supported index creation options, refer to
-   the :manual:`createIndexes </reference/command/createIndexes>`
-   command reference in the MongoDB manual.
+   For a full list of the supported index creation options, refer to the
+   :manual:`createIndexes </reference/command/createIndexes>` command reference
+   in the MongoDB manual.
 
-Output
-------
+   :returns:
 
-Returns the name of the created indexes as an array of strings.
+      The names of the created indexes as an array of strings.
 
 Example
 -------
 
-The following creates two indexes on the ``restaurants`` collection in
-the ``example`` database. One index is a compound index on the
-``borough`` and ``cuisine`` fields and the other is 2dsphere index
-on the ``location`` field with a custom name.
+The following example creates two indexes on the ``restaurants`` collection in
+the ``example`` database. One index is a compound index on the ``borough`` and
+``cuisine`` fields and the other is 2dsphere index on the ``loc`` field with a
+custom name.
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->selectCollection('example', 'restaurants');
 
-   $index = $collection->createIndexes(
-       [ 
+   $indexNames = $collection->createIndexes([
        [ 'key' => [ 'borough' => 1, 'cuisine' => 1] ],
-           [ 'key' => [ 'location' => '2dsphere'], 'name' => 'geo_index'],
+       [ 'key' => [ 'loc' => '2dsphere'], 'name' => 'geo_index' ],
    ]);
 
-   var_dump($index);
+   var_dump($indexNames);
 
-The output would resemble the following::
+The output would then resemble::
 
    array(2) {
      [0]=>
@@ -91,8 +82,8 @@ The output would resemble the following::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::createIndex`
+   - :phpmethod:`MongoDB\\Collection::createIndex()`
    - :doc:`/tutorial/indexes`
-   - :manual:`createIndexes </reference/command/createIndexes>` 
-     command reference in the MongoDB manual
-   - :manual:`Index documentation </indexes>`
+   - :manual:`createIndexes </reference/command/createIndexes>` command
+     reference in the MongoDB manual
+   - :manual:`Index </indexes>` documentation in the MongoDB Manual

docs/reference/method/MongoDBCollection-deleteMany.txt

@@ -13,7 +13,7 @@ MongoDB\\Collection::deleteMany()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::deleteMany($filter, $options)
+.. phpmethod:: MongoDB\\Collection::deleteMany()
 
    Deletes all documents that match the filter criteria.
 
@@ -21,26 +21,25 @@ Definition
 
       function deleteMany($filter, array $options = []): MongoDB\DeleteResult
 
-   :phpmethod:`MongoDB\\Collection::deleteMany` has the following
-   parameters:
+   :phpmethod:`MongoDB\\Collection::deleteMany()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-deleteMany-param.rst
 
-   :phpmethod:`MongoDB\\Collection::deleteMany` supports the following
-   options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-deleteMany-option.rst
 
-Output
-------
+   :returns:
 
-Returns a ``MongoDB\DeleteResult`` object.
+      A :phpclass:`MongoDB\\DeleteResult` object, which encapsulates a
+      :php:`MongoDB\\Driver\\WriteResult <class.mongodb-driver-writeresult>`
+      object.
 
 Example
 -------
 
-The following operation deletes all of the documents in the ``users``
-collection that have ``ny`` as the value for the ``state`` field:
+The following example deletes all of the documents in the ``users`` collection
+that have ``"ny"`` as the value for the ``state`` field:
 
 .. code-block:: php
 
@@ -59,11 +58,10 @@ The output would then resemble::
 
    Deleted 2 document(s)
 
-
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::bulkWrite`
-   - :phpmethod:`MongoDB\\Collection::deleteOne`
+   - :phpmethod:`MongoDB\\Collection::deleteOne()`
+   - :phpmethod:`MongoDB\\Collection::bulkWrite()`
    - :doc:`/tutorial/crud`
-   - :manual:`delete command reference </reference/command/delete`
-     in the MongoDB manual
+   - :manual:`delete </reference/command/delete` command reference in the
+     MongoDB manual
\ No newline at end of file

docs/reference/method/MongoDBCollection-deleteOne.txt

@@ -13,37 +13,35 @@ MongoDB\\Collection::deleteOne()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::deleteOne($filter, $options)
+.. phpmethod:: MongoDB\\Collection::deleteOne()
 
-   Deletes at most one document that matches the filter criteria. If
-   multiple documents match the filter criteria,
-   :phpmethod:`MongoDB\\Collection::deleteOne` deletes the :term:`first
-   <natural order>` matching document.
+   Deletes at most one document that matches the filter criteria. If multiple
+   documents match the filter criteria, only the :term:`first <natural order>`
+   matching document will be deleted.
 
    .. code-block:: php
 
       function deleteOne($filter, array $options = []): MongoDB\DeleteResult
 
-   :phpmethod:`MongoDB\\Collection::deleteMany` has the following
-   parameters:
+   :phpmethod:`MongoDB\\Collection::deleteOne()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-deleteOne-param.rst
 
-   :phpmethod:`MongoDB\\Collection::deleteMany` supports the following
-   options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-deleteOne-option.rst
 
-Output
-------
+   :returns:
 
-Returns a ``MongoDB\DeleteResult`` object.
+      A :phpclass:`MongoDB\\DeleteResult` object, which encapsulates a
+      :php:`MongoDB\\Driver\\WriteResult <class.mongodb-driver-writeresult>`
+      object.
 
 Example
 -------
 
-The following operation deletes the first documents in the ``users``
-collection that has ``ny`` as the value for the ``state`` field:
+The following example deletes one document in the ``users`` collection that has
+has ``"ny"`` as the value for the ``state`` field:
 
 .. code-block:: php
 
@@ -64,8 +62,8 @@ The output would then resemble::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::bulkWrite`
-   - :phpmethod:`MongoDB\\Collection::deleteMany`
+   - :phpmethod:`MongoDB\\Collection::deleteMany()`
+   - :phpmethod:`MongoDB\\Collection::bulkWrite()`
    - :doc:`/tutorial/crud`
    - :manual:`delete command reference </reference/command/delete`
      in the MongoDB manual

docs/reference/method/MongoDBCollection-distinct.txt

@@ -21,7 +21,7 @@ Definition
 
       function distinct($fieldName, $filter = [], array $options = []): mixed[]
 
-   ``distinct`` has the following parameters:
+   :phpmethod:`MongoDB\\Collection::distinct()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-distinct-param.rst
 
@@ -29,10 +29,9 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-distinct-option.rst
 
-Output
-------
+   :returns:
 
-Returns an array of the distinct values.
+      An array of the distinct values.
 
 Examples
 --------
@@ -40,23 +39,20 @@ Examples
 Return Distinct Values for a Field
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following example identifies the distinct values for the
-``borough`` field in the ``restaurants`` collection in the
-``example`` database.
+The following example identifies the distinct values for the ``borough`` field
+in the ``restaurants`` collection in the ``example`` database.
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->example->restaurants;
 
    $distinct = $collection->distinct('borough');
 
    var_dump($distinct);
 
-The output would resemble::
+The output would then resemble::
 
    array(6) {
      [0]=>
@@ -73,24 +69,20 @@ The output would resemble::
      string(13) "Staten Island"
    }
 
-   
 Return Distinct Values Using a Filter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following example identifies the distinct values for the
-``cuisine`` field in the ``restaurants`` collection in the ``example``
-database for documents where the ``borough`` is ``Queens``:
+The following example identifies the distinct values for the ``cuisine`` field
+in the ``restaurants`` collection in the ``example`` database for documents
+where the ``borough`` is ``Queens``:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
-
-   $distinct = $collection->distinct('cuisine', ['borough'=>'Queens']);
+   $collection = (new MongoDB\Client)->example->restaurants;
 
+   $distinct = $collection->distinct('cuisine', ['borough' => 'Queens']);
 
    var_dump($distinct);
 
@@ -249,8 +241,7 @@ The output would then resemble::
      string(29) "Vietnamese/Cambodian/Malaysia"
    }
 
-
 .. seealso::
 
-   - :manual:`distinct </reference/command/distinct>` command
-     reference in the MongoDB manual.
+   - :manual:`distinct </reference/command/distinct>` command reference in the
+     MongoDB manual

docs/reference/method/MongoDBCollection-drop.txt

@@ -13,48 +13,45 @@ MongoDB\\Collection::drop()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::drop
+.. phpmethod:: MongoDB\\Collection::drop()
 
-   Drops the collection.
+   Drop the collection.
 
    .. code-block:: php
 
       function drop(array $options = []): array|object
 
-   ``drop()`` supports the following parameter:
+   :phpmethod:`MongoDB\\Collection::drop()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-drop-param.rst
 
-   The ``$options`` parameter supports the following option:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-drop-option.rst
 
-Output
-------
+   :returns:
 
-Returns the command result document as an array or object, depending
-on the ``typeMap`` specification.
+      An array or object with the result document of the :manual:`drop
+      </reference/command/drop>` command. The return type will depend on the
+      ``typeMap`` option.
 
 Example
 -------
 
-The following operation drops the ``restaurants`` collection in the
-``example`` database:
+The following operation drops the ``restaurants`` collection in the ``example``
+database:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $collection = $database->selectCollection('example','restaurants');
+   $result = $collection->drop();
 
-   $output = $collection->drop();
+   var_dump($result);
 
-   
-   var_dump($output);
-
-The output would resemble::
+The output would then resemble::
 
    object(MongoDB\Model\BSONDocument)#9 (1) {
      ["storage":"ArrayObject":private]=>
@@ -70,7 +67,6 @@ The output would resemble::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Database::dropCollection`
-   - :manual:`drop </reference/command/drop>` command reference in
-     the MongoDB manual.
-
+   - :phpmethod:`MongoDB\\Database::dropCollection()`
+   - :manual:`drop </reference/command/drop>` command reference in the MongoDB
+     manual

docs/reference/method/MongoDBCollection-dropIndex.txt

@@ -13,49 +13,45 @@ MongoDB\\Collection::dropIndex()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::dropIndex($indexName, $options)
+.. phpmethod:: MongoDB\\Collection::dropIndex()
 
-   Drops an index from the collection.
+   Drop an index from the collection.
 
    .. code-block:: php
 
       function dropIndex($indexName, array $options = []): array|object
 
-   ``dropIndex()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::dropIndex()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-dropIndex-param.rst
 
-   The ``$options`` parameter supports the following option:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-dropIndex-option.rst
 
-Output
-------
+   :returns:
 
-Returns the command result document as an array or object, depending
-on the ``typeMap`` specification.
+      An array or object with the result document of the :manual:`dropIndexes
+      </reference/command/dropIndexes>` command. The return type will depend on
+      the ``typeMap`` option.
 
 Example
 -------
 
-The following drops an indexes with name ``borough_1`` from the
-``restaurants`` collection in the ``example`` database:
+The following drops an indexes with name ``borough_1`` from the ``restaurants``
+collection in the ``example`` database:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $collection = $database->selectCollection('example','restaurants');
+   $result = $collection->dropIndex('borough_1');
 
-   $index = $collection->dropIndex( "borough_1" );
+   var_dump($result);
 
-   
-   var_dump($index);
-
-                
-The output would resemble the following::
+The output would then resemble::
 
    object(MongoDB\Model\BSONDocument)#9 (1) {
      ["storage":"ArrayObject":private]=>
@@ -69,8 +65,8 @@ The output would resemble the following::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::dropIndexes`
+   - :phpmethod:`MongoDB\\Collection::dropIndexes()`
    - :doc:`/tutorial/indexes`
-   - :manual:`dropIndexes </reference/command/dropIndexes>` command
-     references in the MongoDB manual.
-   - :manual:`Index documentation </indexes>`
+   - :manual:`dropIndexes </reference/command/dropIndexes>` command reference
+     in the MongoDB manual
+   - :manual:`Index documentation </indexes>` in the MongoDB manual

docs/reference/method/MongoDBCollection-dropIndexes.txt

@@ -13,48 +13,46 @@ MongoDB\\Collection::dropIndexes()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::dropIndexes($options)
+.. phpmethod:: MongoDB\\Collection::dropIndexes()
 
-   Drops **all indexes** in the collection.
+   Drop all indexes in the collection, except for the required index on the
+   ``_id`` field.
 
    .. code-block:: php
 
       function dropIndexes(array $options = []): array|object
 
-   ``dropIndexes()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::dropIndexes()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-dropIndex-param.rst
 
-   The ``$options`` parameter supports the following option:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-dropIndex-option.rst
 
-Output
-------
+   :returns:
 
-Returns the command result document as an array or object, depending
-on the ``typeMap`` specification.
+      An array or object with the result document of the :manual:`dropIndexes
+      </reference/command/dropIndexes>` command. The return type will depend on
+      the ``typeMap`` option.
 
 Example
 -------
 
-The following drops all indexes from the ``restaurants`` collection in
-the ``example`` database:
+The following drops all indexes from the ``restaurants`` collection in the
+``example`` database:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $collection = $database->selectCollection('example','restaurants');
+   $result = $collection->dropIndexes();
 
-   $response = $collection->dropIndexes();
+   var_dump($result);
 
-   var_dump($response);
-
-                
-The output would resemble the following::
+The output would then resemble::
 
    object(MongoDB\Model\BSONDocument)#9 (1) {
      ["storage":"ArrayObject":private]=>
@@ -70,8 +68,8 @@ The output would resemble the following::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::dropIndex`
+   - :phpmethod:`MongoDB\\Collection::dropIndex()`
    - :doc:`/tutorial/indexes`
-   - :manual:`dropIndexes </reference/command/dropIndexes>` command
-     references in the MongoDB manual.
-   - :manual:`Index documentation </indexes>`
+   - :manual:`dropIndexes </reference/command/dropIndexes>` command reference
+     in the MongoDB manual
+   - :manual:`Index documentation </indexes>` in the MongoDB manual

docs/reference/method/MongoDBCollection-find.txt

@@ -10,11 +10,10 @@ MongoDB\\Collection::find()
    :depth: 1
    :class: singlecol
 
-              
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::find
+.. phpmethod:: MongoDB\\Collection::find()
 
    Finds documents matching the query.
 
@@ -22,7 +21,7 @@ Definition
 
       function find($filter = [], array $options = []): MongoDB\Driver\Cursor
 
-   ``find()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::find()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-find-param.rst
 
@@ -30,43 +29,42 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-find-option.rst
 
+   :returns:
 
-Output
-------
-
-Returns a ``MongoDB\Driver\Cursor`` object.
+      A :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>` object.
 
 Examples
 --------
 
-The following example finds restaurants based on the ``cuisine`` and
-``borough`` fields and uses a :manual:`projection
-</tutorial/project-fields-from-query-results>` to limit the fields
-that are returned. It also limits the results to 5 documents.
+The following example finds restaurants based on the ``cuisine`` and ``borough``
+fields and uses a :manual:`projection
+</tutorial/project-fields-from-query-results>` to limit the fields that are
+returned. It also limits the results to 5 documents.
 
 .. code-block:: php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $restaurants = $collection->find(
-       [ 'cuisine' => 'Italian', 'borough' => 'Manhattan' ],
-       [ 'limit' => 5, 
+   $cursor = $collection->find(
+       [
+           'cuisine' => 'Italian',
+           'borough' => 'Manhattan',
+       ],
+       [
+           'limit' => 5,
            'projection' => [
-           'name' => 1, 'borough' => 1, 'cuisine' => 1,
+               'name' => 1,
+               'borough' => 1,
+               'cuisine' => 1,
            ],
        ]
    );
 
-   
-   foreach ($restaurants as $restaurant) {
+   foreach ($cursor as $restaurant) {
       var_dump($restaurant);
    };
 
-The output would resemble:
-
-.. code-block:: none
+The output would then resemble::
 
    object(MongoDB\Model\BSONDocument)#10 (1) {
      ["storage":"ArrayObject":private]=>
@@ -151,6 +149,6 @@ The output would resemble:
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::findOne`
-   - :manual:`find </reference/command/find>` command reference
-     in the MongoDB manual
+   - :phpmethod:`MongoDB\\Collection::findOne()`
+   - :manual:`find </reference/command/find>` command reference in the MongoDB
+     manual

docs/reference/method/MongoDBCollection-findOne.txt

@@ -10,19 +10,18 @@ MongoDB\\Collection::findOne()
    :depth: 1
    :class: singlecol
 
-              
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::findOne
+.. phpmethod:: MongoDB\\Collection::findOne()
 
    Finds a single document matching the query.
 
    .. code-block:: php
 
-      function findOne($filter = [], array $options = []): array|object
+      function findOne($filter = [], array $options = []): array|object|null
 
-   ``findOne()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::findOne()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-findOne-param.rst
 
@@ -30,56 +29,61 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-findOne-option.rst
 
+   :returns:
 
-Output
-------
-
-Returns the :term:`first document <natural order>` that matches the
-query or ``null`` if no document matches the query.
+      An array or object for the :term:`first document <natural order>` document
+      that matched the query, or ``null`` if no document matched the query. The
+      return type will depend on the ``typeMap`` option.
 
 Examples
 --------
 
 The following example finds a restaurant based on the ``cuisine`` and
 ``borough`` fields and uses a :manual:`projection
-</tutorial/project-fields-from-query-results>` to limit the fields
-that are returned.
+</tutorial/project-fields-from-query-results>` to limit the fields that are
+returned.
 
 .. code-block:: php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $restaurants = $collection->findOne(
-       [ 'cuisine' => 'Italian', 'borough' => 'Manhattan'],
-       [ 'limit' => 5, 
+   $restaurant = $collection->findOne(
+       [
+           'cuisine' => 'Italian',
+           'borough' => 'Manhattan',
+       ],
+       [
            'projection' => [
-           'name' => 1, 'borough' => 1, 'cuisine' => 1,
+               'name' => 1,
+               'borough' => 1,
+               'cuisine' => 1,
            ],
        ]
    );
 
-   
-   foreach ($restaurants as $restaurant) {
    var_dump($restaurant);
-   };
 
-The output would resemble:
+The output would then resemble::
 
-.. code-block:: none
-                
-   object(MongoDB\BSON\ObjectID)#11 (1) {
+   object(MongoDB\Model\BSONDocument)#10 (1) {
+     ["storage":"ArrayObject":private]=>
+     array(4) {
+       ["_id"]=>
+       object(MongoDB\BSON\ObjectID)#8 (1) {
          ["oid"]=>
          string(24) "576023c6b02fa9281da3f983"
        }
+       ["borough"]=>
        string(9) "Manhattan"
+       ["cuisine"]=>
        string(7) "Italian"
+       ["name"]=>
        string(23) "Isle Of Capri Resturant"
-
+     }
+   }
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::findOne`
-   - :manual:`find </reference/command/find>` command reference
-     in the MongoDB manual
+   - :phpmethod:`MongoDB\\Collection::find()`
+   - :manual:`find </reference/command/find>` command reference in the MongoDB
+     manual

docs/reference/method/MongoDBCollection-findOneAndDelete.txt

@@ -10,19 +10,19 @@ MongoDB\\Collection::findOneAndDelete()
    :depth: 1
    :class: singlecol
 
-              
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::findOneAndDelete
+.. phpmethod:: MongoDB\\Collection::findOneAndDelete()
 
-   Finds a single document and deletes it.
+   Finds a single document matching the query and deletes it.
 
    .. code-block:: php
 
       function findOneAndDelete($filter = [], array $options = []): object|null
 
-   ``findOne()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::findOneAndDelete()` has the following
+   parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-findOneAndDelete-param.rst
 
@@ -32,39 +32,37 @@ Definition
 
    .. include:: /includes/extracts/bson-deserialization-findOneAndDelete.rst
 
-Output
-------
+   :returns:
 
-Returns the document that was deleted. If no document matched the
-filter, the returned document is ``null``.
+      An object for the document that was deleted, or ``null`` if no document
+      matched the query.
 
 Examples
 --------
 
-The following example deletes the document with ``restaurant_id`` of
-``40375376`` from the ``restaurants`` collection in the ``example``
-database:
+The following example finds and deletes the document with ``restaurant_id`` of
+``"40375376"`` from the ``restaurants`` collection in the ``example`` database:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->example->restaurants;
 
    $deletedRestaurant = $collection->findOneAndDelete(
        [ 'restaurant_id' => '40375376' ],
-       [ 'projection' => [ 'name' => 1, 
+       [
+           'projection' => [
+               'name' => 1,
                'borough' => 1,
-                           'restaurant_id' => 1
-                         ] 
+               'restaurant_id' => 1,
+           ],
        ]
    );
 
-The output would resemble:
+   var_dump($deletedRestaurant);
 
-.. code-block:: none
+The output would then resemble::
 
    object(stdClass)#14 (4) {
      ["_id"]=>
@@ -80,10 +78,9 @@ The output would resemble:
      string(8) "40375376"
    }
 
-
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::findOneAndUpdate`
-   - :phpmethod:`MongoDB\\Collection::findOneAndReplace`
-   - :manual:`findAndModify </reference/command/findAndModify>`
-     command reference in the MongoDB manual
+   - :phpmethod:`MongoDB\\Collection::findOneAndReplace()`
+   - :phpmethod:`MongoDB\\Collection::findOneAndUpdate()`
+   - :manual:`findAndModify </reference/command/findAndModify>` command
+     reference in the MongoDB manual

docs/reference/method/MongoDBCollection-findOneAndReplace.txt

@@ -10,11 +10,10 @@ MongoDB\\Collection::findOneAndReplace()
    :depth: 1
    :class: singlecol
 
-              
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::findOneAndReplace
+.. phpmethod:: MongoDB\\Collection::findOneAndReplace()
 
    Finds a single document matching the query and replaces it.
 
@@ -22,7 +21,8 @@ Definition
 
       function findOneAndReplace($filter, $replacement, array $options = []): object|null
 
-   ``findOneAndReplace()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::findOneAndReplace()` has the following
+   parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-findOneAndReplace-param.rst
 
@@ -32,18 +32,18 @@ Definition
 
    .. include:: /includes/extracts/bson-deserialization-findOneAndReplace.rst
 
-Output
-------
+   :returns:
 
-By default, returns the original document. To return the *new*
-document, use the ``returnDocument`` option. If no document matched
-the query, returns ``null``.
+      An object for either the original or the replaced document, depending on
+      the specified value of the ``returnDocument`` option. By default, the
+      original document is returned. If no document matched the query, ``null``
+      is returned.
 
 Examples
 --------
 
-Consider the following document in the ``restaurants`` collection in
-the ``example`` database:
+Consider the following document in the ``restaurants`` collection in the
+``example`` database:
 
 .. code-block:: javascript
 
@@ -81,31 +81,30 @@ the ``example`` database:
      "restaurant_id" : "41220906"
    }
 
-The following operation replaces the document with ``restaurant_id :
-41220906`` with the new specified document:
+The following operation replaces the document with ``restaurant_id`` of
+``"41220906"`` with a new document:
 
 .. code-block:: php
 
    <?php
 
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $updateRestaurant = $collection->findOneAndReplace(
+   $replacedRestaurant = $collection->findOneAndReplace(
        [ 'restaurant_id' => '41220906' ],
-       [ 'Borough' => 'Staten Island', 
+       [
+           'Borough' => 'Staten Island',
            'cuisine' => 'Italian',
            'grades' => [],
            'name' => 'Staten Island Pastaria',
            'restaurant_id' => '999999999',
        ],
-       [ 'returnDocument' => MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER ]
+       [ 'returnDocument' => MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER ]
    );
 
+   var_dump($replacedRestaurant)
 
-
-   var_dump($updateRestaurant)
-      
-The ``var_dump()`` output contains the new document, as in the following::
+The output would then resemble::
 
    object(stdClass)#14 (6) {
      ["_id"]=>
@@ -128,7 +127,7 @@ The ``var_dump()`` output contains the new document, as in the following::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::findOneAndDelete`
-   - :phpmethod:`MongoDB\\Collection::findOneAndUpdate`
-   - :manual:`findAndModify </reference/command/findAndModify>`
-     command reference in the MongoDB manual
+   - :phpmethod:`MongoDB\\Collection::findOneAndDelete()`
+   - :phpmethod:`MongoDB\\Collection::findOneAndUpdate()`
+   - :manual:`findAndModify </reference/command/findAndModify>` command
+     reference in the MongoDB manual

docs/reference/method/MongoDBCollection-findOneAndUpdate.txt

@@ -10,11 +10,10 @@ MongoDB\\Collection::findOneAndUpdate()
    :depth: 1
    :class: singlecol
 
-              
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::findOneAndUpdate
+.. phpmethod:: MongoDB\\Collection::findOneAndUpdate()
 
    Finds a single document matching the query and updates it.
 
@@ -22,7 +21,8 @@ Definition
 
       function findOneAndUpdate($filter, $update, array $options = []): object|null
 
-   ``findOneAndUpdate()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::findOneAndUpdate()` has the following
+   parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-findOneAndUpdate-param.rst
 
@@ -32,42 +32,66 @@ Definition
 
    .. include:: /includes/extracts/bson-deserialization-findOneAndUpdate.rst
 
-Output
-------
+   :returns:
 
-Returns either the original or the updated document, depending on the
-specified value for the ``returnDocument`` option. By default, the
-original document is returned.
+      An object for either the original or the updated document, depending on
+      the specified value of the ``returnDocument`` option. By default, the
+      original document is returned. If no document matched the query, ``null``
+      is returned.
 
 Examples
 --------
 
-The following operation updates the building number of the restaurant
-with ``restaurant_id : 40361708`` in the ``restaurants`` collection in
-the ``example`` database to ``761``:
+The following operation updates the restaurant with ``restaurant_id`` of
+``"40361708"`` in the ``restaurants`` collection in the ``example`` database by
+setting its building number to ``"761"``:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $updateRestaurant = $collection->findOneAndUpdate(
+   $updatedRestaurant = $collection->findOneAndUpdate(
        [ 'restaurant_id' => '40361708' ],
-       [ '$set' => ['address.building' => '761']],
-       [ 'returnDocument' => MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER ]
+       [ '$set' => [ 'address.building' => '761' ]],
+       [
+           'projection' => [ 'address' => 1 ],
+           'returnDocument' => MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER
+       ]
    );
 
-   
-   var_dump($updateRestaurant)
-                
-
+   var_dump($updatedRestaurant)
+
+The output would then resemble::
+
+   object(stdClass)#16 (2) {
+     ["_id"]=>
+     object(MongoDB\BSON\ObjectID)#10 (1) {
+       ["oid"]=>
+       string(24) "5813a08d29032c6e72d566a7"
+     }
+     ["address"]=>
+     object(stdClass)#15 (4) {
+       ["building"]=>
+       string(3) "761"
+       ["coord"]=>
+       array(2) {
+         [0]=>
+         float(-73.9925306)
+         [1]=>
+         float(40.7309346)
+       }
+       ["street"]=>
+       string(8) "Broadway"
+       ["zipcode"]=>
+       string(5) "10003"
+     }
+   }
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::findOneAndDelete`
-   - :phpmethod:`MongoDB\\Collection::findOneAndReplace`
-   - :manual:`findAndModify </reference/command/findAndModify>` command reference
-     in the MongoDB manual
+   - :phpmethod:`MongoDB\\Collection::findOneAndDelete()`
+   - :phpmethod:`MongoDB\\Collection::findOneAndReplace()`
+   - :manual:`findAndModify </reference/command/findAndModify>` command
+     reference in the MongoDB manual

docs/reference/method/MongoDBCollection-getCollectionName.txt

@@ -4,35 +4,46 @@ MongoDB\\Collection::getCollectionName()
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 Definition
 ----------
 
 .. phpmethod:: MongoDB\\Collection::getCollectionName()
 
-   Returns the name of the current collection.
+   Returns the name of this collection.
 
    .. code-block:: php
 
       function getCollectionName(): string
 
+   :returns:
+
+      The name of this collection as a string.
+
 Example
 -------
 
-The following returns the name of the collection assigned to the
-``$collection`` variable
+The following returns the collection name for the ``zips`` collection in the
+``demo`` database.
 
 .. code-block:: php
 
    <?php
 
    $collection = (new MongoDB\Client)->demo->zips;
-   echo $collection->getCollectionName();
 
-The ``$collection`` variable uses the :phpmethod:`constructor
-<MongoDB\\Collection::__construct>` method to select the ``zips``
-collection in the ``demo`` database, as such, the printed output would
-resemble:
+   echo $collection->getCollectionName();
 
-.. code-block:: none
+The output would then resemble::
 
    zips
+
+.. seealso::
+
+   - :phpmethod:`MongoDB\\Collection::getDatabaseName()`
+   - :phpmethod:`MongoDB\\Collection::getNamespace()`

docs/reference/method/MongoDBCollection-getDatabaseName.txt

@@ -4,35 +4,47 @@ MongoDB\\Collection::getDatabaseName()
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 Definition
 ----------
 
 .. phpmethod:: MongoDB\\Collection::getDatabaseName()
 
-   Returns the name of the current database.
+   Returns the name of the database containing this collection.
 
    .. code-block:: php
 
       function getDatabaseName(): string
 
+   :returns:
+
+      The name of the database containing this collection as a string.
+
 Example
 -------
 
-The following returns the name of the database of the collection
-assigned to the ``$collection`` variable
+The following returns the database name for the ``zips`` collection in the
+``demo`` database.
 
 .. code-block:: php
 
    <?php
 
    $collection = (new MongoDB\Client)->demo->zips;
-   echo $collection->getDatabaseName();
 
-The ``$collection`` variable uses the :phpmethod:`constructor
-<MongoDB\\Collection::__construct>` method to select the ``zips``
-collection in the ``demo`` database, as such, the printed output would
-resemble:
+   echo $collection->getDatabaseName();
 
-.. code-block:: none
+The output would then resemble::
 
    demo
+
+.. seealso::
+
+   - :phpmethod:`MongoDB\\Collection::getCollectionName()`
+   - :phpmethod:`MongoDB\\Collection::getNamespace()`
+

docs/reference/method/MongoDBCollection-getManager.txt

@@ -17,7 +17,7 @@ Definition
 
    Accessor for the
    :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>` used by this
-   :phpclass:`Client <MongoDB\\Collection>`.
+   :phpclass:`Collection <MongoDB\\Collection>`.
 
    .. code-block:: php
 

docs/reference/method/MongoDBCollection-getNamespace.txt

@@ -4,36 +4,47 @@ MongoDB\\Collection::getNamespace()
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 Definition
 ----------
 
 .. phpmethod:: MongoDB\\Collection::getNamespace()
 
-   Returns the :term:`namespace` of the collection. A namespace
-   is the canonical name of an index or collection in MongoDB.
+   Returns the :term:`namespace` of the collection. A namespace is the canonical
+   name of an index or collection in MongoDB.
 
    .. code-block:: php
 
       function getNamespace(): string
 
+   :returns:
+
+      The namespace of this collection as a string.
+
 Example
 -------
 
-The following returns the namespace of the collection
-assigned to the ``$collection`` variable
+The following returns the namespace of the ``zips`` collection in the ``demo``
+database.
 
 .. code-block:: php
 
    <?php
 
    $collection = (new MongoDB\Client)->demo->zips;
-   echo $collection->getNamespace();
 
-The ``$collection`` variable uses the :phpmethod:`constructor
-<MongoDB\\Collection::__construct>` method to select the ``zips``
-collection in the ``demo`` database, as such, the printed output would
-resemble:
+   echo $collection->getNamespace();
 
-.. code-block:: none
+The output would then resemble::
 
    demo.zips
+
+.. seealso::
+
+   - :phpmethod:`MongoDB\\Collection::getCollectionName()`
+   - :phpmethod:`MongoDB\\Collection::getDatabaseName()`

docs/reference/method/MongoDBCollection-insertMany.txt

@@ -10,19 +10,18 @@ MongoDB\\Collection::insertMany()
    :depth: 1
    :class: singlecol
 
-              
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::insertMany
+.. phpmethod:: MongoDB\\Collection::insertMany()
 
-   Inserts one document.
+   Insert multiple documents.
 
    .. code-block:: php
 
       function insertMany(array $documents, array $options = []): MongoDB\InsertManyResult
 
-   ``insertMany()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::insertMany()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-insertMany-param.rst
 
@@ -30,47 +29,44 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-insertMany-option.rst
 
-Output
-------
+   :returns:
 
-Returns a ``MongoDB\InsertManyResult`` object.
+      A :phpclass:`MongoDB\\InsertManyResult` object, which encapsulates a
+      :php:`MongoDB\\Driver\\WriteResult <class.mongodb-driver-writeresult>`
+      object.
 
 Example
 -------
 
 .. start-crud-include
 
-The following operation inserts two documents into the ``users``
-collection in the ``example`` database:
+The following operation inserts two documents into the ``users`` collection
+in the ``example`` database:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('users','restaurants');
+   $collection = (new MongoDB\Client)->example->users;
 
-   $newUsers = $collection->insertMany(
-       [
+   $insertManyResult = $collection->insertMany([
        [
            'username' => 'admin',
            'email' => 'admin@example.com',
-           'name' => 'Admin User'
+           'name' => 'Admin User',
        ],
        [
            'username' => 'test',
            'email' => 'test@example.com',
-           'name' => 'Test User'
-   
+           'name' => 'Test User',
        ],
-       ]
-   );
+   ]);
+
+   printf("Inserted %d document(s)\n", $insertManyResult->getInsertedCount());
 
-   printf("Inserted %d document(s)\n", $newUsers->getInsertedCount());
-   var_dump($newUsers->getInsertedIds());
+   var_dump($insertManyResult->getInsertedIds());
 
-The output would resemble::
+The output would then resemble::
 
    Inserted 2 document(s)
    array(2) {
@@ -90,8 +86,8 @@ The output would resemble::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::bulkWrite`
-   - :phpmethod:`MongoDB\\Collection::insertOne`
+   - :phpmethod:`MongoDB\\Collection::insertOne()`
+   - :phpmethod:`MongoDB\\Collection::bulkWrite()`
    - :doc:`/tutorial/crud`
-   - :manual:`insert </reference/command/insert>` command reference
-     in the MongoDB manual
+   - :manual:`insert </reference/command/insert>` command reference in the
+     MongoDB manual

docs/reference/method/MongoDBCollection-insertOne.txt

@@ -10,19 +10,18 @@ MongoDB\\Collection::insertOne()
    :depth: 1
    :class: singlecol
 
-              
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::insertOne
+.. phpmethod:: MongoDB\\Collection::insertOne()
 
-   Inserts one document.
+   Insert one document.
 
    .. code-block:: php
 
       function insertOne($document, array $options = []): MongoDB\InsertOneResult
 
-   ``insertOne()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::insertOne()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-insertOne-param.rst
 
@@ -30,23 +29,50 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-insertOne-option.rst
 
-Output
-------
+   :returns:
 
-Returns a ``MongoDB\InsertOneResult`` object.
+      A :phpclass:`MongoDB\\InsertOneResult` object, which encapsulates a
+      :php:`MongoDB\\Driver\\WriteResult <class.mongodb-driver-writeresult>`
+      object.
 
 Example
 -------
 
-The following operation inserts a document into the ``users``
-collection in the ``example`` database:
+.. start-crud-include
+
+The following operation inserts a document into the ``users`` collection in the
+``example`` database:
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->example->users;
+
+   $insertOneResult = $collection->insertOne([
+       'username' => 'admin',
+       'email' => 'admin@example.com',
+       'name' => 'Admin User',
+   ]);
+
+   printf("Inserted %d document(s)\n", $insertOneResult->getInsertedCount());
+
+   var_dump($insertOneResult->getInsertedId());
+
+The output would then resemble::
+
+   Inserted 1 document(s)
+   object(MongoDB\BSON\ObjectID)#11 (1) {
+     ["oid"]=>
+     string(24) "579a25921f417dd1e5518141"
+   }
 
-.. include:: /includes/example-insertOne.rst
+.. end-crud-include
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::bulkWrite`
-   - :phpmethod:`MongoDB\\Collection::insertMany`
+   - :phpmethod:`MongoDB\\Collection::insertMany()`
+   - :phpmethod:`MongoDB\\Collection::bulkWrite()`
    - :doc:`/tutorial/crud`
-   - :manual:`insert </reference/command/insert>` command reference
-     in the MongoDB manual
+   - :manual:`insert </reference/command/insert>` command reference in the
+     MongoDB manual

docs/reference/method/MongoDBCollection-listIndexes.txt

@@ -4,7 +4,7 @@ MongoDB\\Collection::listIndexes()
 
 .. default-domain:: mongodb
 
-.. contents::
+.. contents:: On this page
    :local:
    :backlinks: none
    :depth: 1
@@ -13,16 +13,15 @@ MongoDB\\Collection::listIndexes()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::listIndexes($options)
+.. phpmethod:: MongoDB\\Collection::listIndexes()
 
-   Returns information for all indexes for the collection.
+   Returns information for all indexes for this collection.
 
    .. code-block:: php
 
       function listIndexes(array $options = []): MongoDB\Model\IndexInfoIterator
 
-   :phpmethod:`MongoDB\\Collection::listIndexes` supports the
-   following parameter:
+   :phpmethod:`MongoDB\\Collection::listIndexes()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-listIndexes-param.rst
 
@@ -30,30 +29,25 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-listIndexes-option.rst
 
-Output
-------
-
-Elements in the returned iterator are ``MongoDB\Model\IndexInfo``
-objects.
+   :returns:
 
+      A traversable :phpclass:`MongoDB\\Model\IndexInfoIterator`, which
+      contains an :phpclass:`MongoDB\\Model\IndexInfo` object for each index for
+      the collection.
 
 Example
 -------
 
-The following lists information about the indexes on the collection
-assigned to the ``$collection`` variable
+The following example lists all of the indexes for the ``restaurants``
+collection in the ``example`` database:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $indexes = $collection->listIndexes();
-
-   foreach ($indexes as $index) {
+   foreach ($collection->listIndexes() as $index) {
       var_dump($index);
    }
 
@@ -99,14 +93,12 @@ The output would then resemble::
      string(19) "example.restaurants"
    }
 
-
 .. seealso::
 
    - :doc:`/tutorial/indexes`
-
-   - :manual:`listIndexes command </reference/command/listIndexes>` in the MongoDB manual.
-   
-   - :manual:`Index documentation </core/indexes>` in the MongoDB manual.
-   
-   - `MongoDB Specification: Enumerating Collections
+   - :manual:`listIndexes </reference/command/listIndexes>` command reference in
+     the MongoDB manual
+   - :manual:`Index documentation </core/indexes>` in the MongoDB manual
+   - `Enumerating Collections
      <https://github.com/mongodb/specifications/blob/master/source/enumerate-indexes.rst>`_
+     specification

docs/reference/method/MongoDBCollection-replaceOne.txt

@@ -10,19 +10,20 @@ MongoDB\\Collection::replaceOne()
    :depth: 1
    :class: singlecol
 
-              
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::replaceOne
+.. phpmethod:: MongoDB\\Collection::replaceOne()
 
-   Replaces at most one document that matches the filter.
+   Replace at most one document that matches the filter criteria. If multiple
+   documents match the filter criteria, only the :term:`first <natural order>`
+   matching document will be replaced.
 
    .. code-block:: php
 
       function replaceOne($filter, $replacement, array $options = []): MongoDB\UpdateResult
 
-   ``replaceOne()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::replaceOne()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-replaceOne-param.rst
 
@@ -30,27 +31,26 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-replaceOne-option.rst
 
-Output
-------
+   :returns:
 
-Returns a ``MongoDB\UpdateResult`` object.
+      A :phpclass:`MongoDB\\UpdateResult` object, which encapsulates a
+      :php:`MongoDB\\Driver\\WriteResult <class.mongodb-driver-writeresult>`
+      object.
 
 Example
 -------
 
-The following operation replaces the document with ``restaurant_id``
-``40356068`` in the ``restaurants`` collection in the ``example`` database:
+The following example replaces the document with ``restaurant_id`` of
+``"40356068"`` in the ``restaurants`` collection in the ``example`` database:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('users','restaurants');
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $replacement = $collection->replaceOne(
-       [   'restaurant_id' => '40356068'],
+   $updateResult = $collection->replaceOne(
+       [ 'restaurant_id' => '40356068' ],
        [
            'name' => 'New Restaurant',
            'restaurant_id' => '99988877',
@@ -60,55 +60,19 @@ The following operation replaces the document with ``restaurant_id``
        ]
    );
 
+   printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
+   printf("Modified %d document(s)\n", $updateResult->getModifiedCount());
+
+The output would then resemble::
 
-   var_dump($replacement);
-
-The output would resemble:
-
-.. code-block:: none
-                
-   object(MongoDB\UpdateResult)#13 (2) {
-     ["writeResult":"MongoDB\UpdateResult":private]=>
-     object(MongoDB\Driver\WriteResult)#12 (9) {
-       ["nInserted"]=>
-       int(0)
-       ["nMatched"]=>
-       int(1)
-       ["nModified"]=>
-       int(1)
-       ["nRemoved"]=>
-       int(0)
-       ["nUpserted"]=>
-       int(0)
-       ["upsertedIds"]=>
-       array(0) {
-       }
-       ["writeErrors"]=>
-       array(0) {
-       }
-       ["writeConcernError"]=>
-       NULL
-       ["writeConcern"]=>
-       array(4) {
-         ["w"]=>
-         NULL
-         ["wmajority"]=>
-         bool(false)
-         ["wtimeout"]=>
-         int(0)
-         ["journal"]=>
-         NULL
-       }
-     }
-     ["isAcknowledged":"MongoDB\UpdateResult":private]=>
-     bool(true)
-   }
+   Matched 1 document(s)
+   Modified 1 document(s)
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::bulkWrite`
-   - :phpmethod:`MongoDB\\Collection::updateMany`
-   - :phpmethod:`MongoDB\\Collection::updateOne`
+   - :phpmethod:`MongoDB\\Collection::updateMany()`
+   - :phpmethod:`MongoDB\\Collection::updateOne()`
+   - :phpmethod:`MongoDB\\Collection::bulkWrite()`
    - :doc:`/tutorial/crud`
-   - :manual:`update </reference/command/update>` command reference
-     in the MongoDB manual
+   - :manual:`update </reference/command/update>` command reference in the
+     MongoDB manual

docs/reference/method/MongoDBCollection-updateMany.txt

@@ -10,19 +10,18 @@ MongoDB\\Collection::updateMany()
    :depth: 1
    :class: singlecol
 
-              
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::updateMany
+.. phpmethod:: MongoDB\\Collection::updateMany()
 
-   Updates all documents that match the filter criteria.
+   Update all documents that match the filter criteria.
 
    .. code-block:: php
 
       function updateMany($filter, $update, array $options = []): MongoDB\UpdateResult
 
-   ``updateMany()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::updateMany()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-updateMany-param.rst
 
@@ -30,80 +29,40 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-updateMany-option.rst
 
-Output
-------
+   :returns:
 
-Returns a ``MongoDB\UpdateResult`` object.
+      A :phpclass:`MongoDB\\UpdateResult` object, which encapsulates a
+      :php:`MongoDB\\Driver\\WriteResult <class.mongodb-driver-writeresult>`
+      object.
 
 Examples
 --------
 
-The following operation adds a an ``active`` field to all of the documents
-with ``borough: Queens`` with value ``true``:
+The following example updates all of the documents with the ``borough`` of
+``"Queens"`` by setting the ``active`` field to ``true``:
 
 .. code-block:: php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $update = $collection->updateMany(
-          [   'borough' => 'Queens'],
-          [
-              '$set' => [
-                   'active' => 'True'
-              ]
-          ]
+   $updateResult = $collection->updateMany(
+       [ 'borough' => 'Queens' ],
+       [ '$set' => [ 'active' => 'True' ]]
    );
 
-   
-
-   var_dump($update);
+   printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
+   printf("Modified %d document(s)\n", $updateResult->getModifiedCount());
 
 The output would then resemble::
 
-   object(MongoDB\UpdateResult)#13 (2) {
-     ["writeResult":"MongoDB\UpdateResult":private]=>
-     object(MongoDB\Driver\WriteResult)#12 (9) {
-       ["nInserted"]=>
-       int(0)
-       ["nMatched"]=>
-       int(5656)
-       ["nModified"]=>
-       int(5656)
-       ["nRemoved"]=>
-       int(0)
-       ["nUpserted"]=>
-       int(0)
-       ["upsertedIds"]=>
-       array(0) {
-       }
-       ["writeErrors"]=>
-       array(0) {
-       }
-       ["writeConcernError"]=>
-       NULL
-       ["writeConcern"]=>
-       array(4) {
-         ["w"]=>
-         NULL
-         ["wmajority"]=>
-         bool(false)
-         ["wtimeout"]=>
-         int(0)
-         ["journal"]=>
-         NULL
-       }
-     }
-     ["isAcknowledged":"MongoDB\UpdateResult":private]=>
-     bool(true)
-   }
+   Matched 5656 document(s)
+   Modified 5656 document(s)
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::bulkWrite`
-   - :phpmethod:`MongoDB\\Collection::replaceOne`
-   - :phpmethod:`MongoDB\\Collection::updateOne`
+   - :phpmethod:`MongoDB\\Collection::replaceOne()`
+   - :phpmethod:`MongoDB\\Collection::updateOne()`
+   - :phpmethod:`MongoDB\\Collection::bulkWrite()`
    - :doc:`/tutorial/crud`
-   - :manual:`update </reference/command/update>` command reference
-     in the MongoDB manual.
+   - :manual:`update </reference/command/update>` command reference in the
+     MongoDB manual

docs/reference/method/MongoDBCollection-updateOne.txt

@@ -10,19 +10,20 @@ MongoDB\\Collection::updateOne()
    :depth: 1
    :class: singlecol
 
-              
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::updateOne
+.. phpmethod:: MongoDB\\Collection::updateOne()
 
-   Finds a single document matching the query and updates it.
+   Update at most one document that matches the filter criteria. If multiple
+   documents match the filter criteria, only the :term:`first <natural order>`
+   matching document will be updated.
 
    .. code-block:: php
 
       function updateOne($filter, $update, array $options = []): MongoDB\UpdateResult
 
-   ``updateOne()`` supports the following parameters:
+   :phpmethod:`MongoDB\\Collection::updateOne()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-updateOne-param.rst
 
@@ -30,81 +31,40 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-updateOne-option.rst
 
-Output
-------
+   :returns:
 
-Returns a ``MongoDB\UpdateResult`` object.
+      A :phpclass:`MongoDB\\UpdateResult` object, which encapsulates a
+      :php:`MongoDB\\Driver\\WriteResult <class.mongodb-driver-writeresult>`
+      object.
 
 Examples
 --------
 
-The following operation updates the ``name`` of the restaurant with
-``restaurant_id: 40356151`` to "Brunos on Astoria":
+The following example updates one document with the ``restaurant_id`` of
+``"40356151"`` by setting the ``name`` field to ``"Brunos on Astoria"``:
 
 .. code-block:: php
 
-   $database = new MongoDB\Client;
-
-   $collection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->example->restaurants;
 
-   $update = $collection->updateOne(
-          [   'restaurant_id' => '40356151'],
-          [
-              '$set' => [
-                   'name' => 'Brunos on Astoria'
-              ]
-          ]
+   $updateResult = $collection->updateOne(
+       [ 'restaurant_id' => '40356151' ],
+       [ '$set' => [ 'name' => 'Brunos on Astoria' ]]
    );
 
-   
-
-   var_dump($update);
+   printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
+   printf("Modified %d document(s)\n", $updateResult->getModifiedCount());
 
 The output would then resemble::
 
-  object(MongoDB\UpdateResult)#13 (2) {
-     ["writeResult":"MongoDB\UpdateResult":private]=>
-     object(MongoDB\Driver\WriteResult)#12 (9) {
-       ["nInserted"]=>
-       int(0)
-       ["nMatched"]=>
-       int(1)
-       ["nModified"]=>
-       int(1)
-       ["nRemoved"]=>
-       int(0)
-       ["nUpserted"]=>
-       int(0)
-       ["upsertedIds"]=>
-       array(0) {
-       }
-       ["writeErrors"]=>
-       array(0) {
-       }
-       ["writeConcernError"]=>
-       NULL
-       ["writeConcern"]=>
-       array(4) {
-         ["w"]=>
-         NULL
-         ["wmajority"]=>
-         bool(false)
-         ["wtimeout"]=>
-         int(0)
-         ["journal"]=>
-         NULL
-       }
-     }
-     ["isAcknowledged":"MongoDB\UpdateResult":private]=>
-     bool(true)
-   }
-  
+   Matched 1 document(s)
+   Modified 1 document(s)
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::bulkWrite`
-   - :phpmethod:`MongoDB\\Collection::replaceOne`
-   - :phpmethod:`MongoDB\\Collection::updateMany`
+   - :phpmethod:`MongoDB\\Collection::replaceOne()`
+   - :phpmethod:`MongoDB\\Collection::updateMany()`
+   - :phpmethod:`MongoDB\\Collection::bulkWrite()`
    - :doc:`/tutorial/crud`
-   - :manual:`update </reference/command/update>` command reference
-     in the MongoDB manual.
+   - :manual:`update </reference/command/update>` command reference in the
+     MongoDB manual

docs/reference/method/MongoDBCollection-withOptions.txt

@@ -4,19 +4,24 @@ MongoDB\\Collection::withOptions()
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::withOptions($options)
+.. phpmethod:: MongoDB\\Collection::withOptions()
 
-   Returns a clone of the collection, but with different options.
+   Returns a clone of the Collection object, but with different options.
 
    .. code-block:: php
 
       function withOptions(array $options = []): MongoDB\Collection
 
-   :phpmethod:`MongoDB\\Collection::withOptions` supports the
-   following parameter:
+   :phpmethod:`MongoDB\\Collection::withOptions()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-withOptions-param.rst
 
@@ -24,26 +29,26 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-withOptions-option.rst
 
+   :returns:
+
+      A :phpclass:`MongoDB\\Collection` object.
+
 Example
 -------
 
-The following example creates a new collection based on the
-``restaurants`` collection in the ``example`` database with a custom
-read preference:
+The following example clones an existing Collection object with a new read
+preference:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
-
-   $sourceCollection = $database->selectCollection('example','restaurants');
+   $collection = (new MongoDB\Client)->selectCollect('demo', 'restaurants');
 
    $newCollection = $sourceCollection->withOptions([
        'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
    ]);
 
-
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::__construct`
+   - :phpmethod:`MongoDB\\Collection::__construct()`

docs/reference/method/MongoDBCollection__construct.txt

@@ -13,7 +13,7 @@ MongoDB\\Collection::__construct()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Collection::__construct($manager, $databaseName, $collectionName, $options)
+.. phpmethod:: MongoDB\\Collection::__construct()
 
    Constructs a new :phpclass:`Collection <MongoDB\\Collection>` instance.
 
@@ -25,20 +25,24 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBCollection-method-construct-param.rst
 
-   :phpmethod:`MongoDB\\Collection::__construct` supports the following
-   options:
+   The ``$options`` parameter supports the following options:
 
-   .. include:: /includes/apiargs/common-option.rst
+   .. include:: /includes/apiargs/MongoDBCollection-method-construct-option.rst
 
-   If you construct the Collection explicitly, the Collection inherits
-   any options from the ``Manager`` object. If you select the Collection
-   from a :phpclass:`Client <MongoDB\\Client>` or :phpclass:`Database
-   <MongoDB\\Database>` object, the Collection inherits its options
-   from that object.
+Behavior
+--------
+
+If you construct a Collection explicitly, the Collection inherits any options
+from the :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>` object.
+If you select the Collection from a :phpclass:`Client <MongoDB\\Client>` or
+:phpclass:`Database <MongoDB\\Database>` object, the Collection inherits its
+options from that object.
 
 .. todo: add an example
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::withOptions`
-   - :phpmethod:`MongoDB\\Database::selectCollection`
+   - :phpmethod:`MongoDB\\Collection::withOptions()`
+   - :phpmethod:`MongoDB\\Client::selectCollection()`
+   - :phpmethod:`MongoDB\\Database::selectCollection()`
+   - :phpmethod:`MongoDB\\Database::__get()`

docs/tutorial/crud.txt

@@ -33,12 +33,13 @@ The :phpmethod:`MongoDB\\Collection::insertOne` method inserts a single
 document into MongoDB and returns an instance of ``MongoDB\InsertOneResult``,
 which you can use to access the IDs of the inserted document.
 
-.. basic insertOne example:
+.. this uses the insertMany example from the method reference:
 
-.. include:: /includes/example-insertOne.rst
+.. include:: /reference/method/MongoDBCollection-insertOne.txt
+   :start-after: start-crud-include
+   :end-before: end-crud-include
 
-The output includes the ``insertedId`` property, which contains the
-ID of the inserted document.
+The output includes the ID of the inserted document.
 
 If you include an ``_id`` value when inserting a document, MongoDB checks
 to ensure that the ``_id`` value is unique for the collection. If the
@@ -324,8 +325,8 @@ collection data. The |php-library|\'s
 :phpmethod:`MongoDB\\Collection::aggregate` method returns a
 :php:`traversable <traversable>` object, which you can iterate upon to
 access the results of the aggregation operation. Refer to the
-:phpmethod:`MongoDB\\Collection::aggregate` method's :ref:`output
-reference <php-agg-method-output>` for more about the method's output.
+:phpmethod:`MongoDB\\Collection::aggregate` method's :ref:`behavior
+reference <php-agg-method-behavior>` for more about the method's output.
 
 The following example lists the 5 US states with the most zip codes
 associated with them: