Merge pull request #276

docs/includes/apiargs-MongoDBClient-method-construct-driverOptions.yaml

+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, which determines how BSON documents are converted to PHP
+  values. 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: ~
+optional: true
+...

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

@@ -2,46 +2,41 @@ arg_name: param
 name: $uri
 type: string
 description: |
-  The URI of the standalone, replica set, or sharded cluster to which to connect. Refer
-  to the :manual:`MongoDB connection string reference </reference/connection-string>`
-  for formatting.
-  
-  Defaults to ``mongodb://localhost:27017`` if unspecified.
+  The URI of the standalone, replica set, or sharded cluster to which to
+  connect. Refer to the :manual:`MongoDB connection string reference
+  </reference/connection-string>` for formatting.
+
+  Defaults to ``"mongodb://127.0.0.1:27017"`` if unspecified.
 interface: phpmethod
-operation: MongoDB\\Client::__construct
+operation: ~
 optional: true
-position: 1
 ---
 arg_name: param
 name: $uriOptions
 type: array
 description: |
-  Specifies additional URI options, such as authentication credentials
-  or query string parameters. The options specified in ``$uriOptions``
-  take precedence over any analogous options present in the
-  ``$uri`` string.
-post: |
+  Specifies additional URI options, such as authentication credentials or query
+  string parameters. The options specified in ``$uriOptions`` take precedence
+  over any analogous options present in the ``$uri`` string.
+
   Refer to the :php:`MongoDB\\Driver\\Manager::__construct()
-  <mongodb-driver-manager.construct>` extension reference and
-  :manual:`MongoDB connection string </reference/connection-string>`
-  documentation for valid options.
+  <mongodb-driver-manager.construct>` extension reference and :manual:`MongoDB
+  connection string </reference/connection-string>` documentation for accepted
+  options.
 interface: phpmethod
-operation: MongoDB\\Client::__construct
+operation: ~
 optional: true
-position: 2
 ---
 arg_name: param
 name: $driverOptions
 type: array
 description: |
-  Specify driver-specific options. In addition to any
-  options supported by the :php:`extension <mongodb-driver-manager>`,
-  the |php-library| allows you to specify a default ``typeMap`` to
-  apply to the cursors it creates. Refer to the driver's
-  :php:`Persistence documentation <mongodb-persistence>` for more
-  about type maps.
+  Specify driver-specific options, such as SSL options. In addition to any
+  options supported by the :php:`extension <mongodb-driver-manager>`, the
+  |php-library| allows you to specify a default :php:`type map
+  <manual/en/mongodb.persistence.deserialization.php#mongodb.persistence.typemaps>`
+  to apply to the cursors it creates.
 interface: phpmethod
-operation: MongoDB\\Client::__construct
+operation: ~
 optional: true
-position: 3
-...
\ No newline at end of file
+...

docs/includes/apiargs-MongoDBClient-method-dropDatabase-option.yaml

-arg_name: option
-interface: phpmethod
-operation: MongoDB\\Client::dropDatabase
 source:
   file: apiargs-common-option.yaml
   ref: typeMap
-position: 1
+post: |
+  This will be used for the returned command result document.
+---
+arg_name: option
+name: writeConcern
+type: :php:`MongoDB\\Driver\\WriteConcern <class.mongodb-driver-writeconcern>`
+description: |
+  :manual:`Write concern </reference/write-concern>` to use for the operation.
+  Defaults to the client's write concern.
+
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
+interface: phpmethod
+operation: ~
+optional: true
 ...

docs/includes/apiargs-MongoDBClient-method-dropDatabase-param.yaml

 source:
-  ref: $databaseName
   file: apiargs-common-param.yaml
-arg_name: param
-interface: phpmethod
-operation: MongoDB\\Client::dropDatabase
+  ref: $databaseName
+replacement:
+  action: " to drop"
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-arg_name: param
-interface: phpmethod
-operation: MongoDB\\Client::dropDatabase
-position: 2
+  ref: $options
 ...

docs/includes/apiargs-MongoDBClient-method-get-param.yaml

 source:
-  ref: $databaseName
   file: apiargs-common-param.yaml
-arg_name: param
-interface: phpmethod
-operation: MongoDB\\Client::__get
+  ref: $databaseName
+replacement:
+  action: " to select"
 ...

docs/includes/apiargs-MongoDBClient-method-listDatabases-option.yaml

 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-position: 1
 ...

docs/includes/apiargs-MongoDBClient-method-listDatabases-param.yaml

 source:
-  ref: $options
   file: apiargs-common-param.yaml
-arg_name: param
-interface: phpmethod
-operation: MongoDB\\Client::listDatabases
-position: 1
+  ref: $options
 ...

docs/includes/apiargs-MongoDBClient-method-selectCollection-option.yaml

+source:
+  file: apiargs-common-option.yaml
+  ref: readConcern
+replacement:
+  resource: "collection"
+  parent: "client"
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: readPreference
+replacement:
+  resource: "collection"
+  parent: "client"
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: typeMap
+replacement:
+  parent: "client"
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: writeConcern
+replacement:
+  resource: "collection"
+  parent: "client"
+...

docs/includes/apiargs-MongoDBClient-method-selectCollection-param.yaml

+source:
+  file: apiargs-common-param.yaml
+  ref: $databaseName
+replacement:
+  action: " containing the collection to select"
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $collectionName
+replacement:
+  action: " to select"
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

docs/includes/apiargs-MongoDBClient-method-selectDatabase-option.yaml

 source:
-  ref: readConcern
   file: apiargs-common-option.yaml
-operation: MongoDB\\Client::selectDatabase
+  ref: readConcern
 replacement:
   resource: "database"
+  parent: "client"
 ---
 source:
-  ref: readPreference
   file: apiargs-common-option.yaml
-operation: MongoDB\\Client::selectDatabase
+  ref: readPreference
 replacement:
   resource: "database"
+  parent: "client"
 ---
 source:
-  ref: typeMap
   file: apiargs-common-option.yaml
-operation: MongoDB\\Client::selectDatabase
+  ref: typeMap
+replacement:
+  parent: "client"
 ---
 source:
-  ref: writeConcern
   file: apiargs-common-option.yaml
-operation: MongoDB\\Client::selectDatabase
+  ref: writeConcern
 replacement:
   resource: "database"
-...
\ No newline at end of file
+  parent: "client"
+...

docs/includes/apiargs-MongoDBClient-method-selectDatabase-param.yaml

 source:
-  ref: $databaseName
   file: apiargs-common-param.yaml
-operation: MongoDB\\Client::selectDatabase
-position: 1
+  ref: $databaseName
+replacement:
+  action: " to select"
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Client::selectDatabase
-position: 2
+  ref: $options
 ...

docs/includes/apiargs-MongoDBCollection-common-option.yaml

+arg_name: option
+name: bypassDocumentValidation
+type: boolean
+description: |
+   If ``true``, allows the write operation to circumvent document level
+   validation. Defaults to ``false``.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: collation
+type: array|object
+description: |
+   :manual:`Collation </reference/collation>` allows users to specify
+   language-specific rules for string comparison, such as rules for lettercase
+   and accent marks. When specifying collation, the ``locale`` field is
+   mandatory; all other collation fields are optional. For descriptions of the
+   fields, see :manual:`Collation Document
+   <reference/collation/#collation-document>`.
+
+   If the collation is unspecified but the collection has a default collation,
+   the operation uses the collation specified for the collection. If no
+   collation is specified for the collection or for the operation, MongoDB uses
+   the simple binary comparison used in prior versions for string comparisons.
+
+   This option is available in MongoDB 3.4+ and will result in an exception at
+   execution time if specified for an older server version.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: readConcern
+type: :php:`MongoDB\\Driver\\ReadConcern <class.mongodb-driver-readconcern>`
+description: |
+   :manual:`Read concern </reference/read-concern>` to use for the operation.
+   Defaults to the collection's read concern.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: readPreference
+type: :php:`MongoDB\\Driver\\ReadPreference <class.mongodb-driver-readpreference>`
+description: |
+   :manual:`Read preference </reference/read-preference>` to use for the
+   operation. Defaults to the collection's read preference.
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: typeMap
+replacement:
+  parent: "collection"
+---
+arg_name: option
+name: writeConcern
+type: :php:`MongoDB\\Driver\\WriteConcern <class.mongodb-driver-writeconcern>`
+description: |
+   :manual:`Write concern </reference/write-concern>` to use for the operation.
+   Defaults to the collection's write concern.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: upsert
+type: boolean
+description: |
+   If set to ``true``, creates a new document when no document matches the query
+   criteria. The default value is ``false``, which does not insert a new
+   document when no match is found.
+interface: phpmethod
+operation: ~
+optional: true
+...

docs/includes/apiargs-MongoDBCollection-common-param.yaml

+arg_name: param
+name: $filter
+type: array|object
+description: |
+  The filter criteria that specifies the documents{{action}}.
+interface: phpmethod
+operation: ~
+optional: false
+replacement:
+  action: ""
+---
+arg_name: param
+name: $replacement
+type: array|object
+description: |
+  The replacement document.
+interface: phpmethod
+operation: ~
+optional: false
+---
+arg_name: param
+name: $update
+type: array|object
+description: |
+  Specifies the field and value combinations to update and any relevant update
+  operators. ``$update`` uses MongoDB's :method:`update operators
+  </reference/operator/update>`.
+interface: phpmethod
+operation: ~
+optional: false
+...

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

@@ -2,72 +2,81 @@ 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
+operation: ~
 optional: true
-position: 1
 ---
 arg_name: option
 name: batchSize
 type: integer
 description: |
-  The number of documents to return per batch
+  Specifies the initial batch size for the cursor. A batchSize of ``0`` means an
+  empty first batch and is useful for quickly returning a cursor or failure
+  message without doing significant server-side work.
+
+  .. note::
+
+     This is not supported for inline aggregation results (i.e. ``useCursor``
+     option is ``false`` or the server version is < 2.6).
 interface: phpmethod
-operation: MongoDB\\Collection::aggregate
+operation: ~
 optional: true
-position: 2
 ---
 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::aggregate
-position: 5
+post: |
+  This only applies when using the :ref:`$out <agg-out>` stage.
+
+  Document validation requires MongoDB 3.2 or later: if you are using an earlier
+  version of MongoDB, this option will be ignored.
 ---
 source:
-  ref: maxTimeMS
   file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::aggregate
-position: 4
+  ref: maxTimeMS
 ---
 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readConcern
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::selectDatabase
-replacement:
-  resource: "aggregation"
-position: 5
 ---
 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readPreference
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::selectDatabase
-replacement:
-  resource: "aggregation"
-position: 6
 ---
 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: typeMap
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::selectDatabase
-position: 7
+post: |
+  .. 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
+arg_name: option
 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
+operation: ~
 optional: true
-position: 8  
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: writeConcern
+post: |
+  This only applies when the :ref:`$out <agg-out>` stage is specified.
+
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
 ...

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

@@ -2,15 +2,13 @@ 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
+operation: ~
+optional: false
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::aggregate
-position: 2
-...
\ No newline at end of file
+  ref: $options
+...

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

 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::bulkWrite
-position: 1
 ---
 arg_name: option
 name: ordered
 type: boolean
 description: |
-  If ``true``: when an insert fails, the operation returns without performing the
-  remaining writes. 
-  
-  If ``false``: when a write fails, the operation will continue with the
-  remaining writes, if any. 
-  
+  If ``true``: when a single write fails, the operation returns without
+  performing the remaining writes.
+
+  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
-position: 2
+operation: ~
+optional: true
 ---
 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::bulkWrite
-replacement:
-  resource: "write"
-position: 3
 ...

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

@@ -2,17 +2,18 @@ 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
-  
+
      [
          [ 'deleteMany' => [ $filter ] ],
          [ 'deleteOne'  => [ $filter ] ],
@@ -21,19 +22,16 @@ description: |
          [ 'updateMany' => [ $filter, $update, $options ] ],
          [ '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
+operation: ~
 optional: true
-position: 1
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::bulkWrite
-interface: phpmethod
-position: 2
-...
\ No newline at end of file
+  ref: $options
+...

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

+source:
+  file: apiargs-common-option.yaml
+  ref: readConcern
+replacement:
+  resource: "collection"
+  parent: "manager"
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: readPreference
+replacement:
+  resource: "collection"
+  parent: "manager"
+---
+source:
+  file: apiargs-MongoDBClient-method-construct-driverOptions.yaml
+  ref: typeMap
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: writeConcern
+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
-operation: MongoDB\\Collection::__construct
-optional: false
-position: 1
+source:
+  file: apiargs-common-param.yaml
+  ref: $manager
 ---
 source:
-  ref: $databaseName
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::__construct
-replacement:
-  select: ""
-position: 2
+  ref: $databaseName
 ---
 source:
-  ref: $collectionName
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::__construct
-replacement:
-  select: ""
-position: 3
+  ref: $collectionName
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::__construct
-position: 4
-...
\ No newline at end of file
+  ref: $options
+...

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

+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
+---
 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 from which a name will be derived.
 interface: phpmethod
-operation: MongoDB\\Collection::count
-position: 1
+operation: ~
+optional: true
 ---
 arg_name: option
 name: limit
 type: integer
 description: |
-  The maximum number of documents to return.
-optional: true
+  The maximum number of matching documents to return.
 interface: phpmethod
-operation: MongoDB\\Collection::count
-position: 2
+operation: ~
+optional: true
 ---
 source:
-  ref: maxTimeMS
   file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::count
-position: 3
+  ref: maxTimeMS
 ---
 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readConcern
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::count
-replacement:
-  resource: "count"
-position: 4
 ---
 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readPreference
-  file: apiargs-common-option.yaml
-replacement:
-  resource: "count"
-position: 5
 ---
 arg_name: option
 name: skip
 type: integer
 description: |
-  The number of documents to skip before returning the documents.
-optional: true
+  The number of matching documents to skip before returning results.
 interface: phpmethod
-operation: MongoDB\\Collection::count
-position: 6
+operation: ~
+optional: true
 ...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::count
-position: 1
+optional: true
+replacement:
+  action: " to count"
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::count
-position: 2
+  ref: $options
 ...

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

@@ -4,9 +4,15 @@ type: boolean
 description: |
   Creates a :manual:`unique </core/index-unique>` index.
 interface: phpmethod
-operation: MongoDB\\Collection::createIndex
+operation: ~
 optional: true
-position: 1
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
+pre: |
+  Specifies the :manual:`collation
+  </reference/bson-type-comparison-order/#collation>` for the index.
 ---
 arg_name: option
 name: partialFilterExpression
@@ -14,9 +20,8 @@ type: array|object
 description: |
   Creates a :manual:`partial </core/index-partial>` index.
 interface: phpmethod
-operation: MongoDB\\Collection::createIndex
+operation: ~
 optional: true
-position: 2
 ---
 arg_name: option
 name: sparse
@@ -24,9 +29,8 @@ type: boolean
 description: |
   Creates a :manual:`sparse </core/index-sparse>` index.
 interface: phpmethod
-operation: MongoDB\\Collection::createIndex
+operation: ~
 optional: true
-position: 3
 ---
 arg_name: option
 name: expireAfterSeconds
@@ -34,66 +38,47 @@ type: integer
 description: |
   Creates a :manual:`TTL </core/index-ttl>` index.
 interface: phpmethod
-operation: MongoDB\\Collection::createIndex
+operation: ~
 optional: true
-position: 4
 ---
 arg_name: option
 name: name
 type: string
-description: |  
-  Specifies the name for the index. By default, MongoDB creates index
+description: |
+  A name that uniquely identifies the index. By default, MongoDB creates index
   names based on the key.
 interface: phpmethod
-operation: MongoDB\\Collection::createIndex
+operation: ~
 optional: true
-position: 5
 ---
 arg_name: option
 name: background
 type: string
-description: |  
+description: |
   Instructs MongoDB to build the index :manual:`as a background
   </core/index-creation>` process.
 interface: phpmethod
-operation: MongoDB\\Collection::createIndex
+operation: ~
 optional: true
-position: 6
 ---
 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.
-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).
+  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 override the default version 2.
 interface: phpmethod
-operation: MongoDB\\Collection::createIndex
+operation: ~
 optional: true
-position: 8
 ---
 source:
-  ref: maxTimeMS
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::createIndex
-position: 9
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: writeConcern
+post: |
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
 ...

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

@@ -3,22 +3,18 @@ name: $key
 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 ];
 
-operation: MongoDB\\Collection::createIndex
+     [ 'username' => -1 ]
 interface: phpmethod
+operation: ~
 optional: false
-position: 1
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Collection::createIndex
-position: 2
-...
\ No newline at end of file
+...

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

+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: writeConcern
+post: |
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
+...

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

+arg_name: param
+name: $indexes
+type: array
+description: |
+  The indexes to create on the collection.
+
+  For example, the following specifies a unique index on the ``username`` field
+  and a compound index on the ``email`` and ``createdAt`` fields:
+
+  .. code-block:: php
+
+     [
+         [ 'key' => [ 'username' => -1 ], 'unique' => true ],
+         [ 'key' => [ 'email' => 1, 'createdAt' => 1 ] ],
+     ]
+interface: phpmethod
+operation: ~
+optional: false
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

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

 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::deleteMany
-replacement:
-  resource: "delete"
-position: 1
 ...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::deleteMany
+optional: false
 replacement:
-  verb: "delete"
-position: 1
+  action: " to delete"
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::deleteMany
-position: 2
+  ref: $options
 ...

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

 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::deleteOne
-replacement:
-  resource: "delete"
-position: 1
 ...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::deleteOne
+optional: false
 replacement:
-  verb: "delete"
-position: 1
+  action: " to delete"
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::deleteOne
-position: 2
+  ref: $options
 ...

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

 source:
-  ref: maxTimeMS
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
+---
+source:
   file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::distinct
-position: 1
+  ref: maxTimeMS
 ---
 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readConcern
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::distinct
-replacement:
-  resource: "distinct"
-position: 2
 ---
 source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readPreference
-  file: apiargs-common-option.yaml
-replacement:
-  resource: "distinct"
-position: 3
 ...

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

@@ -4,19 +4,17 @@ type: string
 description: |
   The field for which to return distinct values.
 interface: phpmethod
-operation: MongoDB\\Collection::distinct
+operation: ~
 optional: false
-position: 1
 ---
 source:
-  file: apiargs-common-param.yaml
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-position: 2
 optional: true
+replacement:
+  action: " from which to retrieve the distinct values"
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::count
-position: 3
+  ref: $options
 ...

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

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Collection::drop
-position: 1
-...
\ No newline at end of file
+post: |
+  This will be used for the returned command result document.
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: writeConcern
+post: |
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
+...

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

 source:
   file: apiargs-common-param.yaml
   ref: $options
-interface: phpmethod
-operation: MongoDB\\Collection::drop
-position: 1
-...
\ No newline at end of file
+...

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

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Collection::dropIndex
-position: 1
-...
\ No newline at end of file
+post: |
+  This will be used for the returned command result document.
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: writeConcern
+post: |
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
+...

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

@@ -2,18 +2,14 @@ arg_name: param
 name: $indexName
 type: string
 description: |
-  The name of the index to drop. View the existing indexes on the
-  collection using the :phpmethod:`listIndexes
-  <MongoDB\\Collection::listIndexes>` method.
+  The name of the index to drop. View the existing indexes on the collection
+  using the :phpmethod:`listIndexes() <MongoDB\\Collection::listIndexes>`
+  method.
 interface: phpmethod
-operation: MongoDB\\Collection::dropIndex
+operation: ~
 optional: false
-position: 1
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-interface: phpmethod
-operation: MongoDB\\Collection::dropIndex
-position: 2
-...
\ No newline at end of file
+...

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

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Collection::dropIndexes
-position: 1
-...
\ No newline at end of file
+post: |
+  This will be used for the returned command result document.
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: writeConcern
+post: |
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
+...

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

 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Collection::dropIndexes
-position: 1
-...
\ No newline at end of file
+...

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

-name: sort
+arg_name: option
+name: projection
 type: array|object
-optional: true
 description: |
-   The sort specification for the ordering of the results.
-arg_name: field
-operation: MongoDB\\Collection::find
+  The :ref:`projection specification <projections>` to determine which fields to
+  include in the returned documents. See :manual:`Project Fields to Return from
+  Query </tutorial/project-fields-from-query-results>` and
+  :manual:`Projection Operators </reference/operator/projection>` in the MongoDB
+  manual.
 interface: phpmethod
-position: 2
+operation: ~
+optional: true
 ---
-name: projection
+arg_name: option
+name: sort
 type: array|object
-optional: true
 description: |
-   The :ref:`projection specification <projections>` to determine
-   which fields to include in the returned documents. See
-   :manual:`Project Fields to Return from Query
-   </tutorial/project-fields-from-query-results>` in the MongoDB
-   manual.   
-arg_name: field
-operation: MongoDB\\Collection::find
+  The sort specification for the ordering of the results.
 interface: phpmethod
-position: 1
+operation: ~
+optional: true
 ---
+arg_name: option
 name: skip
 type: integer
-optional: true
 description: |
-   Number of documents to skip. Defaults to 0.
-arg_name: field
-operation: MongoDB\\Collection::find
+  Number of documents to skip. Defaults to ``0``.
 interface: phpmethod
-position: 3
+operation: ~
+optional: true
 ---
+arg_name: option
 name: limit
 type: integer
-optional: true
 description: |
-   The maximum number of documents to return. If unspecified,
-   then defaults to no limit. A limit of 0 is equivalent to setting no
-   limit.
-arg_name: field
-operation: MongoDB\\Collection::find
+  The maximum number of documents to return. If unspecified, then defaults to no
+  limit. A limit of ``0`` is equivalent to setting no limit.
 interface: phpmethod
-position: 4
+operation: ~
+optional: true
 ---
+arg_name: option
 name: batchSize
 type: integer
-optional: true
 description: |
-   The number of documents to return in the first batch.
-   Defaults to 101. A batchSize of 0 means that the cursor will be
-   established, but no documents will be returned in the first batch.
+  The number of documents to return in the first batch. Defaults to ``101``. A
+  batchSize of ``0`` means that the cursor will be established, but no documents
+  will be returned in the first batch.
 
-   Unlike the previous wire protocol version, a batchSize of 1 for
-   the :dbcommand:`find` command does not close the cursor.
-arg_name: field
-operation: MongoDB\\Collection::find
+  Unlike the previous wire protocol version, a batchSize of ``1`` for the
+  :dbcommand:`find` command does not close the cursor.
 interface: phpmethod
-position: 5
+operation: ~
+optional: true
 ---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
+---
+arg_name: option
 name: comment
 type: string
-optional: true
 description: |
-   A comment to attach to the query to help interpret and trace query
-   :dbcommand:`profile` data.
-arg_name: field
-operation: MongoDB\\Collection::find
+  A comment to attach to the query to help interpret and trace query
+  :dbcommand:`profile` data.
 interface: phpmethod
-position: 6
+operation: ~
+optional: true
 ---
 arg_name: option
 name: cursorType
 type: integer
 description: |
-  Indicates the type of cursor to use. The cursor types are
-  ``MongoDB\Operation\Find`` class constants. 
-  
-  Must be either
-  ``NON_TAILABLE``, ``TAILABLE``, or ``TAILABLE_AWAIT``. The default is
-  ``NON_TAILABLE``.
+  Indicates the type of cursor to use. ``cursorType`` supports the following
+  values:
+
+   - ``MongoDB\Operation\Find::NON_TAILABLE`` (*default*)
+   - ``MongoDB\Operation\Find::TAILABLE``
 interface: phpmethod
-operation: MongoDB\\Collection::find
+operation: ~
 optional: true
-position: 7
 ---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-operation: MongoDB\\Collection::find
-position: 8
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readConcern
-operation: MongoDB\\Collection::find
-position: 9
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readPreference
-pre: |
-  For use with MongoDB 3.0 and earlier.
-operation: MongoDB\\Collection::find
-position: 10
 ---
+arg_name: option
 name: oplogReplay
 type: boolean
-optional: true
 description: |
-  Internal use for replica sets. To use oplogReplay, you must include
-  the following condition in the filter:
+  Internal use for replica sets. To use ``oplogReplay``, you must include the
+  following condition in the filter:
 
   .. code-block:: javascript
 
      { ts: { $gte: <timestamp> } }
-     
-  The :php:`MongoDB\\BSON\\Timestamp <class.mongodb-bson-timestamp>`
-  class reference describes how to represent MongoDB's BSON
-  timestamp type with PHP.
-arg_name: field
-operation: MongoDB\\Collection::find
+
+  The :php:`MongoDB\\BSON\\Timestamp <class.mongodb-bson-timestamp>` class
+  reference describes how to represent MongoDB's BSON timestamp type with PHP.
 interface: phpmethod
-position: 11
+operation: ~
+optional: true
 ---
+arg_name: option
 name: noCursorTimeout
 type: boolean
-optional: true
 description: |
-   Prevents the server from timing out idle cursors after an inactivity
-   period (10 minutes).
-arg_name: field
-operation: MongoDB\\Collection::find
+  Prevents the server from timing out idle cursors after an inactivity period
+  (10 minutes).
 interface: phpmethod
-position: 12
+operation: ~
+optional: true
 ---
+arg_name: option
 name: allowPartialResults
 type: boolean
-optional: true
 description: |
-   For queries against a sharded collection, returns partial results from
-   the :program:`mongos` if some shards are unavailable instead of
-   throwing an error.
-arg_name: field
-operation: MongoDB\\Collection::find
+  For queries against a sharded collection, returns partial results from the
+  :program:`mongos` if some shards are unavailable instead of throwing an error.
 interface: phpmethod
-position: 13
+operation: ~
+optional: true
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Collection::find
-position: 14
 ---
 arg_name: option
 name: modifiers
-type: array
+type: array|object
 description: |
-  Meta-operators that modify the output or behavior of a query.
-  :manual:`Cursor Methods </reference/method/js-cursor`> describes the
-  query modification methods available in MongoDB.
+  Meta-operators that modify the output or behavior of a query. :manual:`Cursor
+  Methods </reference/method/js-cursor`> describes the query modification
+  methods available in MongoDB.
 interface: phpmethod
-operation: MongoDB\\Collection::find
+operation: ~
 optional: true
-position: 15
 ...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::find
+optional: true
 replacement:
-  verb: "query"
-position: 1
+  action: " to query"
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::find
-position: 2
+  ref: $options
 ...

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

 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
   ref: projection
-operation: MongoDB\\Collection::findOne
-position: 1
 ---
 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
   ref: sort
-operation: MongoDB\\Collection::findOne
-position: 2
 ---
 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
   ref: skip
-operation: MongoDB\\Collection::findOne
-position: 3
 ---
 source:
-  file: apiargs-MongoDBCollection-method-find-option.yaml
-  ref: comment
-operation: MongoDB\\Collection::findOne
-position: 4
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
 ---
 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
-  ref: modifiers
-operation: MongoDB\\Collection::findOne
-position: 5
+  ref: comment
 ---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-operation: MongoDB\\Collection::findOne
-position: 6
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readConcern
-operation: MongoDB\\Collection::findOne
-position: 7
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readPreference
-pre: |
-  For use with MongoDB 3.0 and earlier.
-operation: MongoDB\\Collection::findOne
-position: 8
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Collection::findOne
-position: 9
-...
\ No newline at end of file
+post: |
+  This will be used for the returned result document.
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: modifiers
+...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::findOne
+optional: true
 replacement:
-  verb: "query"
-position: 1
+  action: " to query"
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::findOne
-position: 2
+  ref: $options
 ...

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

 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
   ref: projection
-operation: MongoDB\\Collection::findOneAndDelete
-position: 1
 ---
 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
   ref: sort
-operation: MongoDB\\Collection::findOneAndDelete
-position: 2
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
 ---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-operation: MongoDB\\Collection::findOneAndDelete
-position: 3
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Collection::findOneAndDelete
-position: 4
-...
\ No newline at end of file
+post: |
+  This is not supported for server versions prior to 3.2 and will be ignored if
+  used.
+...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::findOneAndDelete
+optional: false
 replacement:
-  verb: "query"
-position: 1
+  action: " to delete"
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::findOneAndDelete
-position: 2
+  ref: $options
 ...

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

 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
   ref: projection
-operation: MongoDB\\Collection::findOneAndReplace
-position: 1
 ---
 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
   ref: sort
-operation: MongoDB\\Collection::findOneAndReplace
-position: 2
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
 ---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-operation: MongoDB\\Collection::findOneAndReplace
-position: 3
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-operation: MongoDB\\Collection::findOneAndReplace
-position: 4
 ---
-source:
-  file: apiargs-MongoDBCollection-method-findOneAndUpdate-option.yaml
-  ref: returnDocument
-operation: MongoDB\\Collection::findOneAndReplace
-position: 5
+arg_name: option
+name: returnDocument
+type: integer
+description: |
+  Specifies whether to return the document before the replacement is applied, or
+  after. ``returnDocument`` supports the following values:
+
+  - ``MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_BEFORE`` (*default*)
+  - ``MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER``
+interface: phpmethod
+operation: ~
+optional: true
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: upsert
-operation: MongoDB\\Collection::findOneAndReplace
-position: 6
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Collection::findOneAndReplace
-position: 7
-...
\ No newline at end of file
+post: |
+  This is not supported for server versions prior to 3.2 and will be ignored if
+  used.
+...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::findOneAndReplace
-replacement:
-  verb: "query"
 optional: false
-position: 1
+replacement:
+  action: " to replace"
 ---
-arg_name: param
-name: $replacement
-type: array|object
-description: |
-  The document to replace.
-interface: phpmethod
-operation: MongoDB\\Collection::findOneAndReplace
-optional: false
-position: 2
+source:
+  file: apiargs-MongoDBCollection-common-param.yaml
+  ref: $replacement
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::findOneAndReplace
-position: 3
+  ref: $options
 ...

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

 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
   ref: projection
-operation: MongoDB\Collection::findOneAndUpdate
-position: 1
 ---
 source:
   file: apiargs-MongoDBCollection-method-find-option.yaml
   ref: sort
-operation: MongoDB\Collection::findOneAndUpdate
-position: 2
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
 ---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-operation: MongoDB\Collection::findOneAndUpdate
-position: 3
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-operation: MongoDB\Collection::findOneAndUpdate
-position: 4
 ---
 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
-position: 5
+operation: ~
+optional: true
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: upsert
-operation: MongoDB\\Collection::findOneAndUpdate
-position: 6
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-operation: MongoDB\Collection::findOneAndUpdate
-position: 7
-...
\ No newline at end of file
+post: |
+  This is not supported for server versions prior to 3.2 and will be ignored if
+  used.
+...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::findOneAndUpdate
-replacement:
-  verb: "query"
 optional: false
-position: 1
+replacement:
+  action: " to update"
 ---
-arg_name: param
-name: $update
-type: array|object
-description: |
-  Specifies the field and value combinations to update and any
-  relevant update operators. ``$update`` uses MongoDB's
-  :method:`update operators </reference/operator/update>`.
-interface: phpmethod
-operation: MongoDB\\Collection::findOneAndUpdate
-optional: false
-position: 2
+source:
+  file: apiargs-MongoDBCollection-common-param.yaml
+  ref: $update
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::findOneAndUpdate
-position: 3
+  ref: $options
 ...

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

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-operation: MongoDB\\Collection::insertMany
-position: 1
 ---
 source:
   file: apiargs-MongoDBCollection-method-bulkWrite-option.yaml
   ref: ordered
-operation: MongoDB\\Collection::insertMany
-position: 2
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Collection::insertMany
-position: 3
-...
\ No newline at end of file
+...

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

@@ -4,13 +4,10 @@ type: array
 description: |
   The documents to insert into the collection.
 interface: phpmethod
-operation: MongoDB\\Collection::insertMany
+operation: ~
 optional: false
-position: 1
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Collection::insertMany
-position: 2
-...
\ No newline at end of file
+...

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

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-operation: MongoDB\\Collection::insertOne
-position: 1
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Collection::insertOne
-position: 2
-...
\ No newline at end of file
+...

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

@@ -4,13 +4,10 @@ type: array|object
 description: |
   The document to insert into the collection.
 interface: phpmethod
-operation: MongoDB\\Collection::insertOne
+operation: ~
 optional: false
-position: 1
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Collection::insertOne
-position: 2
-...
\ No newline at end of file
+...

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

 source:
-  ref: maxTimeMS
   file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::listIndexes
-position: 1
+  ref: maxTimeMS
 ...

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

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

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

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: upsert
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-operation: MongoDB\\Collection::replaceOne
-position: 1
 ---
 source:
-  file: apiargs-common-option.yaml
-  ref: upsert
-operation: MongoDB\\Collection::replaceOne
-position: 2
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Collection::replaceOne
-position: 3
-...
\ No newline at end of file
+...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::replaceOne
-replacement:
-  verb: "query"
 optional: false
-position: 1
+replacement:
+  action: " to replace"
 ---
-arg_name: param
-name: $replacement
-type: array
-description: |
-  The document to replace.
-interface: phpmethod
-operation: MongoDB\\Collection::replaceOne
-optional: false
-position: 2
+source:
+  file: apiargs-MongoDBCollection-common-param.yaml
+  ref: $replacement
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::replaceOne
-position: 3
+  ref: $options
 ...

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

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: upsert
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-operation: MongoDB\\Collection::updateMany
-position: 1
 ---
 source:
-  file: apiargs-common-option.yaml
-  ref: upsert
-operation: MongoDB\\Collection::updateMany
-position: 2
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Collection::updateMany
-position: 3
-...
\ No newline at end of file
+...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::updateMany
-replacement:
-  verb: "query"
 optional: false
-position: 1
+replacement:
+  action: " to update"
 ---
 source:
-  file: apiargs-MongoDBCollection-method-findOneAndUpdate-param.yaml
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $update
-operation: MongoDB\\Collection::updateMany
-optional: false
-position: 2
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::updateMany
-position: 3
+  ref: $options
 ...

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

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: upsert
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-operation: MongoDB\\Collection::updateOne
-position: 1
 ---
 source:
-  file: apiargs-common-option.yaml
-  ref: upsert
-operation: MongoDB\\Collection::updateOne
-position: 2
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Collection::updateOne
-position: 3
-...
\ No newline at end of file
+...

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

 source:
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $filter
-  file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::updateOne
-replacement:
-  verb: "query"
 optional: false
-position: 1
+replacement:
+  action: " to update"
 ---
 source:
-  file: apiargs-MongoDBCollection-method-findOneAndUpdate-param.yaml
+  file: apiargs-MongoDBCollection-common-param.yaml
   ref: $update
-operation: MongoDB\\Collection::updateOne
-optional: false
-position: 2
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Collection::updateOne
-position: 3
+  ref: $options
 ...

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

 source:
   file: apiargs-common-option.yaml
   ref: readConcern
-operation: MongoDB\\Collection::withOptions
-description: |
-  The default read concern to use for collection operations. Defaults
-  to the original Collection's specified read concern.
+replacement:
+  resource: "collection"
+  parent: "original collection"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
-operation: MongoDB\\Collection::withOptions
-description: |
-  The default read preference to use for collection operations.
-  Defaults to the original Collection's read preference.
+replacement:
+  resource: "collection"
+  parent: "original collection"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Collection::withOptions
-description: |
-  Default type map for cursors and BSON documents. Defaults to the
-  original Collection's type map value.
+replacement:
+  parent: "original collection"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Collection::withOptions
-description: |
-  The default write concern to use for collection operations. Defaults
-  to the original Collection's specified write concern.
-...
\ No newline at end of file
+replacement:
+  resource: "collection"
+  parent: "original collection"
+...

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

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

docs/includes/apiargs-MongoDBDatabase-common-option.yaml

+source:
+  file: apiargs-common-option.yaml
+  ref: typeMap
+replacement:
+  parent: "database"
+---
+arg_name: option
+name: writeConcern
+type: :php:`MongoDB\\Driver\\WriteConcern <class.mongodb-driver-writeconcern>`
+description: |
+   :manual:`Write concern </reference/write-concern>` to use for the operation.
+   Defaults to the database's write concern.
+interface: phpmethod
+operation: ~
+optional: true
+...

docs/includes/apiargs-MongoDBDatabase-method-command-option.yaml

 source:
   file: apiargs-common-option.yaml
   ref: readPreference
-operation: MongoDB\\Database::command
-position: 1
+description: |
+   :manual:`Read preference </reference/read-preference>` to use for the
+   operation. Defaults to the database's read preference.
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBDatabase-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Database::command
-position: 2
 ...

docs/includes/apiargs-MongoDBDatabase-method-command-param.yaml

 arg_name: param
 name: $command
-type: string
+type: array|object
 description: |
-  The name of the :manual:`database command </reference/command>`
-  to execute.
+  The :manual:`database command </reference/command>` document.
 interface: phpmethod
-operation: MongoDB\\Database::command
+operation: ~
 optional: false
-position: 1
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Database::command
-position: 2
 ...

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

 source:
   file: apiargs-common-option.yaml
   ref: readConcern
-operation: MongoDB\\Database::__construct
-position: 1
+replacement:
+  resource: "database"
+  parent: "manager"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
-operation: MongoDB\\Database::__construct
-position: 2
+replacement:
+  resource: "database"
+  parent: "manager"
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBClient-method-construct-driverOptions.yaml
   ref: typeMap
-operation: MongoDB\\Database::__construct
-position: 3
 ---
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Database::__construct
-position: 4
-...
\ No newline at end of file
+replacement:
+  resource: "database"
+  parent: "manager"
+...

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

 source:
-  file: apiargs-MongoDBCollection-method-construct-param.yaml
+  file: apiargs-common-param.yaml
   ref: $manager
-operation: MongoDB\\Database::__construct
-position: 1
 ---
 source:
-  ref: $databaseName
   file: apiargs-common-param.yaml
-operation: MongoDB\\Database::__construct
-position: 2
+  ref: $databaseName
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Database::__construct
-position: 2
-...
\ No newline at end of file
+  ref: $options
+...

docs/includes/apiargs-MongoDBDatabase-method-createCollection-param.yaml

 source:
   file: apiargs-common-param.yaml
   ref: $collectionName
-operation: MongoDB\\Database::createCollection
-position: 1
-optional: false
+replacement:
+  action: " to create"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Database::createCollection
-position: 2
-optional: true
-...
\ No newline at end of file
+...

docs/includes/apiargs-MongoDBDatabase-method-drop-option.yaml

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBDatabase-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Database::dropCollection
-position: 1
-...
\ No newline at end of file
+post: |
+  This will be used for the returned command result document.
+---
+source:
+  file: apiargs-MongoDBDatabase-common-option.yaml
+  ref: writeConcern
+post: |
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
+...

docs/includes/apiargs-MongoDBDatabase-method-drop-param.yaml

-source:
-  file: apiargs-common-param.yaml
-  ref: $collectionName
-operation: MongoDB\\Database::dropCollection
-position: 1
-optional: false
----
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Database::dropCollection
-position: 2
-optional: true
-...
\ No newline at end of file
+...

docs/includes/apiargs-MongoDBDatabase-method-dropCollection-option.yaml

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBDatabase-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Database::dropCollection
-position: 1
-...
\ No newline at end of file
+post: |
+  This will be used for the returned command result document.
+---
+source:
+  file: apiargs-MongoDBDatabase-common-option.yaml
+  ref: writeConcern
+post: |
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
+...

docs/includes/apiargs-MongoDBDatabase-method-dropCollection-param.yaml

 source:
   file: apiargs-common-param.yaml
   ref: $collectionName
-operation: MongoDB\\Database::dropCollection
-position: 1
-optional: false
+replacement:
+  action: " to drop"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Database::dropCollection
-position: 2
-optional: true
-...
\ No newline at end of file
+...

docs/includes/apiargs-MongoDBDatabase-method-get-param.yaml

 source:
   file: apiargs-common-param.yaml
   ref: $collectionName
-operation: MongoDB\\Database::__get
-position: 1
-...
\ No newline at end of file
+replacement:
+  action: " to select"
+...

docs/includes/apiargs-MongoDBDatabase-method-listCollections-option.yaml

-source:
-  file: apiargs-common-option.yaml
-  ref: readConcern
-operation: MongoDB\\Database::listCollections
-position: 1
----
-source:
-  file: apiargs-common-option.yaml
-  ref: readPreference
-operation: MongoDB\\Database::listCollections
-position: 2
----
-source:
-  file: apiargs-common-option.yaml
-  ref: typeMap
-operation: MongoDB\\Database::listCollections
-position: 3
+arg_name: option
+name: filter
+type: array|object
+description: |
+  A query expression to filter the list of collections.
+
+  You can specify a query expression on the collection ``name`` and ``options``.
+interface: phpmethod
+operation: ~
+optional: true
 ---
 source:
   file: apiargs-common-option.yaml
-  ref: writeConcern
-operation: MongoDB\\Database::listCollections
-position: 4
-...
\ No newline at end of file
+  ref: maxTimeMS
+...

docs/includes/apiargs-MongoDBDatabase-method-listCollections-param.yaml

 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Database::listCollections
-position: 1
-optional: true
-...
\ No newline at end of file
+...

docs/includes/apiargs-MongoDBDatabase-method-selectCollection-option.yaml

 source:
   file: apiargs-common-option.yaml
   ref: readConcern
-operation: MongoDB\\Database::selectCollection
-position: 1
+replacement:
+  resource: "collection"
+  parent: "database"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
-operation: MongoDB\\Database::selectCollection
-position: 2
+replacement:
+  resource: "collection"
+  parent: "database"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Database::selectCollection
-position: 3
+replacement:
+  parent: "database"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Database::selectCollection
-position: 4
-...
\ No newline at end of file
+replacement:
+  resource: "collection"
+  parent: "database"
+...

docs/includes/apiargs-MongoDBDatabase-method-selectCollection-param.yaml

 source:
   file: apiargs-common-param.yaml
   ref: $collectionName
-operation: MongoDB\\Database::selectCollection
-position: 1
-optional: false
+replacement:
+  action: " to select"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Database::selectCollection
-position: 2
-...
\ No newline at end of file
+...

docs/includes/apiargs-MongoDBDatabase-method-selectGridFSBucket-option.yaml

+arg_name: option
+name: bucketName
+type: string
+description: |
+  The bucket name, which will be used as a prefix for the files and chunks
+  collections. Defaults to ``"fs"``.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: chunkSizeBytes
+type: integer
+description: |
+  The chunk size in bytes. Defaults to ``261120`` (i.e. 255 KiB).
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: readConcern
+replacement:
+  resource: "bucket"
+  parent: "database"
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: readPreference
+replacement:
+  resource: "bucket"
+  parent: "database"
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: writeConcern
+replacement:
+  resource: "bucket"
+  parent: "database"
+...

docs/includes/apiargs-MongoDBDatabase-method-selectGridFSBucket-param.yaml

+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

docs/includes/apiargs-MongoDBDatabase-method-withOptions-option.yaml

 source:
   file: apiargs-common-option.yaml
   ref: readConcern
-operation: MongoDB\\Database::withOptions
-description: |
-  The default read concern to use for database operations. Defaults
-  to the original Databases's specified read concern.
+replacement:
+  resource: "database"
+  parent: "original database"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
-operation: MongoDB\\Database::withOptions
-description: |
-  The default read preference to use for database operations.
-  Defaults to the original Database's read preference.
+replacement:
+  resource: "database"
+  parent: "original database"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Database::withOptions
-description: |
-  Default type map for cursors and BSON documents. Defaults to the
-  original Database's type map value.
+replacement:
+  parent: "original database"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Database::withOptions
-description: |
-  The default write concern to use for database operations. Defaults
-  to the original Database's specified write concern.
-...
\ No newline at end of file
+replacement:
+  resource: "database"
+  parent: "original database"
+...

docs/includes/apiargs-MongoDBDatabase-method-withOptions-param.yaml

 source:
-  ref: $options
   file: apiargs-common-param.yaml
-operation: MongoDB\\Database::withOptions
-position: 1
+  ref: $options
 ...

docs/includes/apiargs-MongoDBGridFSBucket-common-option.yaml

+arg_name: option
+name: _id
+type: mixed
+description: |
+  Value to use as the file document identifier. Defaults to a new
+  :php:`MongoDB\\BSON\\ObjectID <class.mongodb-bson-objectid>` object.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: chunkSizeBytes
+type: integer
+description: |
+  The chunk size in bytes. Defaults to the bucket's ``chunkSizeBytes`` option.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: metadata
+type: array|object
+description: |
+  User data for the ``metadata`` field of the file document. If not specified,
+  the ``metadata`` field will not be set on the file document.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: revision
+type: integer
+description: |
+  The revision of the file to retrieve. Files with the name ``filename`` will be
+  differentiated by their ``uploadDate`` field.
+
+  Revision numbers are defined as follows:
+
+  - 0 = the original stored file
+  - 1 = the first revision
+  - 2 = the second revision
+  - etc...
+  - -2 = the second most recent revision
+  - -1 = the most recent revision
+
+   Defaults to -1 (i.e. the most recent revision).
+interface: phpmethod
+operation: ~
+optional: true
+...

docs/includes/apiargs-MongoDBGridFSBucket-common-param.yaml

+arg_name: param
+name: $filename
+type: string
+description: |
+  The ``filename`` of the file{{action}}.
+interface: phpmethod
+operation: ~
+optional: false
+replacement:
+  action: ""
+---
+arg_name: param
+name: $id
+type: mixed
+description: |
+  The ``_id`` of the file{{action}}.
+interface: phpmethod
+operation: ~
+optional: false
+replacement:
+  action: ""
+---
+arg_name: param
+name: $stream
+type: resource
+description: |
+  The GridFS stream resource.
+interface: phpmethod
+operation: ~
+---
+arg_name: param
+name: $destination
+type: resource
+description: |
+  Writable stream, to which the GridFS file's contents will be written.
+interface: phpmethod
+operation: ~
+optional: false
+...

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

+arg_name: option
+name: bucketName
+type: string
+description: |
+  The bucket name, which will be used as a prefix for the files and chunks
+  collections. Defaults to ``"fs"``.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: chunkSizeBytes
+type: integer
+description: |
+  The chunk size in bytes. Defaults to ``261120`` (i.e. 255 KiB).
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: readConcern
+replacement:
+  resource: "bucket"
+  parent: "database"
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: readPreference
+replacement:
+  resource: "bucket"
+  parent: "database"
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: writeConcern
+replacement:
+  resource: "bucket"
+  parent: "database"
+...

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

+source:
+  file: apiargs-common-param.yaml
+  ref: $manager
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $databaseName
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-delete-param.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $id
+replacement:
+  resource: " to delete"
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-downloadToStream-param.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $id
+replacement:
+  resource: " to download"
+---
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $destination
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-downloadToStreamByName-option.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: revision
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-downloadToStreamByName-param.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $filename
+replacement:
+  resource: " to download"
+---
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $destination
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

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

+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: projection
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: sort
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: skip
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: limit
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: batchSize
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: collation
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: comment
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: cursorType
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: maxTimeMS
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: readConcern
+description: |
+   :manual:`Read concern </reference/read-concern>` to use for the operation.
+   Defaults to the bucket's read concern.
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: readPreference
+description: |
+   :manual:`Read preference </reference/read-preference>` to use for the
+   operation. Defaults to the bucket's read preference.
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: oplogReplay
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: noCursorTimeout
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: allowPartialResults
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: typeMap
+replacement:
+  parent: "bucket"
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: modifiers
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-getFileDocumentForStream-param.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $stream
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-getFileIdForStream-param.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $stream
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-openDownloadStream-param.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $id
+replacement:
+  resource: " to download"
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-openDownloadStreamByName-option.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: revision
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-openDownloadStreamByName-param.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $filename
+replacement:
+  resource: " to download"
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-openUploadStream-option.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: _id
+---
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: chunkSizeBytes
+---
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: metadata
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-openUploadStream-param.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $filename
+replacement:
+  resource: " to create"
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-rename-param.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $id
+replacement:
+  resource: " to rename"
+---
+arg_name: param
+name: $newFilename
+type: string
+description: |
+  The new ``filename`` value.
+interface: phpmethod
+operation: ~
+optional: false
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-uploadFromStream-option.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: _id
+---
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: chunkSizeBytes
+---
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: metadata
+...

docs/includes/apiargs-MongoDBGridFSBucket-method-uploadFromStream-param.yaml

+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $filename
+replacement:
+  resource: " to create"
+---
+arg_name: param
+name: $source
+type: resource
+description: |
+  Readable stream, from which the new GridFS file's contents will be read.
+interface: phpmethod
+operation: ~
+optional: false
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...