Refactor option/param includes and document MongoDB 3.4 features

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

@@ -4,9 +4,8 @@ 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:
+  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
 
@@ -16,7 +15,6 @@ description: |
          'root' => 'MongoDB\Model\BSONDocument',
      ]
 interface: phpmethod
-operation: MongoDB\\Client::__construct
+operation: ~
 optional: true
-position: 1
 ...

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

@@ -6,11 +6,10 @@ description: |
   connect. Refer to the :manual:`MongoDB connection string reference
   </reference/connection-string>` for formatting.
 
-  Defaults to ``mongodb://127.0.0.1:27017`` if unspecified.
+  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
@@ -19,15 +18,14 @@ 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: |
+
   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
+  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
@@ -39,7 +37,6 @@ description: |
   <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
 ...

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

 source:
   file: apiargs-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Client::dropDatabase
+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: |
-  Type map for BSON deserialization. This will be used for the returned command
-  result document. Defaults to the clients's type map.
+  :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:
   file: apiargs-common-param.yaml
   ref: $databaseName
-operation: MongoDB\\Client::dropDatabase
-position: 1
 replacement:
   action: " to drop"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Client::dropDatabase
-position: 2
 ...

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

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

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

 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-operation: MongoDB\\Client::listDatabases
 ...

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

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

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

 source:
   file: apiargs-common-param.yaml
   ref: $databaseName
-operation: MongoDB\\Client::selectCollection
-position: 1
 replacement:
   action: " containing the collection to select"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $collectionName
-operation: MongoDB\\Client::selectCollection
-position: 2
 replacement:
   action: " to select"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Client::selectCollection
-position: 3
 ...

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

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

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

@@ -3,68 +3,59 @@ 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``.
+  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-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-operation: MongoDB\\Collection::aggregate
-position: 3
+post: |
+  This only applies when using the :pipeline:`$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:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-operation: MongoDB\\Collection::aggregate
-position: 4
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readConcern
-operation: MongoDB\\Collection::aggregate
-position: 5
-replacement:
-  resource: "aggregation"
-  parent: "collection"
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: readPreference
-operation: MongoDB\\Collection::aggregate
-position: 6
-replacement:
-  resource: "aggregation"
-  parent: "collection"
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   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.
-
+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: |
@@ -77,7 +68,15 @@ description: |
   ``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 ``$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

@@ -5,12 +5,10 @@ description: |
   Specifies an :manual:`aggregation pipeline </core/aggregation-pipeline>`
   operation.
 interface: phpmethod
-operation: MongoDB\\Collection::aggregate
-position: 1
+operation: ~
+optional: false
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Collection::aggregate
-position: 2
 ...

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

 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
-operation: MongoDB\\Collection::bulkWrite
-position: 1
 ---
 arg_name: option
 name: ordered
@@ -16,16 +14,10 @@ description: |
 
   The default is ``true``.
 interface: phpmethod
-operation: MongoDB\\Collection::bulkWrite
+operation: ~
 optional: true
-position: 2
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBCollection-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Collection::bulkWrite
-replacement:
-  resource: "write"
-  parent: "collection"
-position: 3
 ...

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

@@ -22,20 +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 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:
   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"
@@ -10,39 +8,17 @@ replacement:
 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-MongoDBClient-method-construct-driverOptions.yaml
+  ref: typeMap
 ---
 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

 source:
   file: apiargs-common-param.yaml
   ref: $manager
-operation: MongoDB\\Collection::__construct
-position: 1
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $databaseName
-operation: MongoDB\\Collection::__construct
-position: 2
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $collectionName
-operation: MongoDB\\Collection::__construct
-position: 3
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Collection::__construct
-position: 4
 ...

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

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

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

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

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,20 +38,18 @@ 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 names
-  based on the key.
+  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
@@ -56,9 +58,8 @@ 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
@@ -69,15 +70,15 @@ description: |
 
   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.
+  ``2dsphereIndexVersion`` enables you to override the default version 2.
 interface: phpmethod
-operation: MongoDB\\Collection::createIndex
+operation: ~
 optional: true
-position: 7
 ---
 source:
-  ref: maxTimeMS
-  file: apiargs-common-option.yaml
-operation: MongoDB\\Collection::createIndex
-position: 8
+  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

@@ -10,14 +10,11 @@ description: |
   .. code-block:: php
 
      [ 'username' => -1 ]
-operation: MongoDB\\Collection::createIndex
 interface: phpmethod
+operation: ~
 optional: false
-position: 1
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Collection::createIndex
-position: 2
 ...

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
+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
 ...

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
+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
 ...

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
+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
 ...

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
 interface: phpmethod
-position: 6
+operation: ~
+optional: true
 ---
 arg_name: option
 name: cursorType
@@ -80,87 +77,70 @@ description: |
    - ``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
+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
+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
 ---
 arg_name: option
 name: returnDocument
 type: integer
 description: |
-  Specifies whether to return the document before the replacementi applied, or
+  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: MongoDB\Collection::findOneAndUpdate
+operation: ~
 optional: true
-position: 5
 ---
 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
+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
@@ -32,19 +28,17 @@ description: |
   - ``MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_BEFORE`` (*default*)
   - ``MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER``
 interface: phpmethod
-operation: MongoDB\Collection::findOneAndUpdate
+operation: ~
 optional: true
-position: 5
 ---
 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
+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
 ...

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
 ...

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
 ...

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
 ...

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
 ...

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
 ...

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
 ...

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.
+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: |
-  The read preference to use when executing the command. This may be used when
-  issuing the command to a replica set or shard cluster to ensure that the
-  driver sets the wire protocol accordingly or adds the read preference to the
-  command document, respectively. Defaults to the Database's read preference.
+   :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
-description: |
-  Type map for BSON deserialization. This will be applied to the returned
-  cursor. Defaults to the database's type map.
 ...

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

@@ -4,13 +4,10 @@ type: array|object
 description: |
   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"
@@ -10,39 +8,17 @@ replacement:
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
-operation: MongoDB\\Database::__construct
-position: 2
 replacement:
   resource: "database"
   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\\Database::__construct
-optional: true
-position: 3
+source:
+  file: apiargs-MongoDBClient-method-construct-driverOptions.yaml
+  ref: typeMap
 ---
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Database::__construct
-position: 4
 replacement:
   resource: "database"
   parent: "manager"

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

 source:
   file: apiargs-common-param.yaml
   ref: $manager
-operation: MongoDB\\Database::__construct
-position: 1
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $databaseName
-operation: MongoDB\\Database::__construct
-position: 2
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Collection::__construct
-position: 3
 ...

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

@@ -11,9 +11,8 @@ description: |
 
   .. deprecated:: 3.2. The ``autoIndexId`` option will be removed in MongoDB 3.4.
 interface: phpmethod
-operation: MongoDB\\Database::createCollection
+operation: ~
 optional: true
-position: 1
 ---
 arg_name: option
 name: capped
@@ -22,9 +21,15 @@ description: |
   To create a capped collection, specify ``true``. If you specify ``true``, you
   must also set a maximum size in the ``size`` option.
 interface: phpmethod
-operation: MongoDB\\Database::createCollection
+operation: ~
 optional: true
-position: 3
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
+pre: |
+  Specifies the :manual:`collation
+  </reference/bson-type-comparison-order/#collation>` for the collection.
 ---
 arg_name: option
 name: flags
@@ -48,9 +53,8 @@ description: |
      :manual:`db.createCollection()
      </reference/method/db.createCollection>` for more information.
 interface: phpmethod
-operation: MongoDB\\Database::createCollection
+operation: ~
 optional: true
-position: 4
 ---
 arg_name: option
 name: indexOptionDefaults
@@ -68,31 +72,26 @@ description: |
   and logged to the :term:`oplog` during replication to support replica sets
   with members that use different storage engines.
 interface: phpmethod
-operation: MongoDB\\Database::createCollection
+operation: ~
 optional: true
-position: 5
 ---
 arg_name: option
 name: max
 type: integer
 description: |
-   The maximum number of documents allowed in the capped collection. The
-   ``size`` option takes precedence over this limit. If a capped
-   collection reaches the ``size`` limit before it reaches the maximum
-   number of documents, MongoDB removes old documents. If you prefer to
-   use the ``max`` limit, ensure that the ``size`` limit, which is
-   required for a capped collection, is sufficient to contain the
-   maximum number of documents.
+  The maximum number of documents allowed in the capped collection. The ``size``
+  option takes precedence over this limit. If a capped collection reaches the
+  ``size`` limit before it reaches the maximum number of documents, MongoDB
+  removes old documents. If you prefer to use the ``max`` limit, ensure that the
+  ``size`` limit, which is required for a capped collection, is sufficient to
+  contain the maximum number of documents.
 interface: phpmethod
-operation: MongoDB\\Database::createCollection
+operation: ~
 optional: true
-position: 6
 ---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-operation: MongoDB\\Database::createCollection
-position: 7
 ---
 arg_name: option
 name: size
@@ -103,9 +102,8 @@ description: |
   make space for the new documents. The ``size`` option is required for capped
   collections and ignored for other collections.
 interface: phpmethod
-operation: MongoDB\\Database::createCollection
+operation: ~
 optional: true
-position: 8
 ---
 arg_name: option
 name: storageEngine
@@ -123,18 +121,14 @@ description: |
   validated and logged to the :term:`oplog` during replication to support
   replica sets with members that use different storage engines.
 interface: phpmethod
-operation: MongoDB\\Database::createCollection
+operation: ~
 optional: true
-position: 9
 ---
 source:
-  file: apiargs-common-option.yaml
+  file: apiargs-MongoDBDatabase-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Database::createCollection
-position: 10
-description: |
-  Type map for BSON deserialization. This will be used for the returned command
-  result document. Defaults to the database's type map.
+post: |
+  This will be used for the returned command result document.
 ---
 arg_name: option
 name: validator
@@ -160,10 +154,9 @@ description: |
        ``local``, and ``config`` databases.
 
      - You cannot specify a validator for ``system.*`` collections.
-operation: MongoDB\\Database::createCollection
+operation: ~
 interface: phpmethod
 optional: true
-position: 11
 ---
 arg_name: option
 name: validationAction
@@ -194,9 +187,8 @@ description: |
         - Documents do not have to pass validation. If the document fails
           validation, the write operation logs the validation failure.
 interface: phpmethod
-operation: MongoDB\\Database::createCollection
+operation: ~
 optional: true
-position: 12
 ---
 arg_name: option
 name: validationLevel
@@ -226,7 +218,13 @@ description: |
           documents. Do not apply rules to updates on existing *invalid*
           documents.
 interface: phpmethod
-operation: MongoDB\\Database::createCollection
+operation: ~
 optional: true
-position: 13
+---
+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-createCollection-param.yaml

 source:
   file: apiargs-common-param.yaml
   ref: $collectionName
-operation: MongoDB\\Database::createCollection
-position: 1
 replacement:
   action: " to create"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Database::createCollection
-position: 2
 ...

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::drop
-position: 1
-description: |
-  Type map for BSON deserialization. This will be used for the returned command
-  result document. Defaults to the database's type map.
+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: $options
-operation: MongoDB\\Database::drop
-position: 1
 ...

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
-description: |
-  Type map for BSON deserialization. This will be used for the returned command
-  result document. Defaults to the database's type map.
+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
 replacement:
   action: " to drop"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Database::dropCollection
-position: 2
 ...

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

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

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

@@ -2,15 +2,14 @@ arg_name: option
 name: filter
 type: array|object
 description: |
-  Query by which to filter collections.
+  A query expression to filter the list of collections.
+
+  You can specify a query expression on the collection ``name`` and ``options``.
 interface: phpmethod
-operation: MongoDB\\Database::listCollections
+operation: ~
 optional: true
-position: 1
 ---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-operation: MongoDB\\Database::listCollections
-position: 2
 ...

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

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

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"
@@ -10,8 +8,6 @@ replacement:
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
-operation: MongoDB\\Database::selectCollection
-position: 2
 replacement:
   resource: "collection"
   parent: "database"
@@ -19,16 +15,12 @@ replacement:
 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
 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
 replacement:
   action: " to select"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Database::selectCollection
-position: 2
 ...

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

@@ -5,9 +5,8 @@ description: |
   The bucket name, which will be used as a prefix for the files and chunks
   collections. Defaults to ``"fs"``.
 interface: phpmethod
-operation: MongoDB\\Database::selectGridFSBucket
+operation: ~
 optional: true
-position: 1
 ---
 arg_name: option
 name: chunkSizeBytes
@@ -15,15 +14,12 @@ type: integer
 description: |
   The chunk size in bytes. Defaults to ``261120`` (i.e. 255 KiB).
 interface: phpmethod
-operation: MongoDB\\Database::selectGridFSBucket
+operation: ~
 optional: true
-position: 2
 ---
 source:
   file: apiargs-common-option.yaml
   ref: readConcern
-operation: MongoDB\\Database::selectGridFSBucket
-position: 3
 replacement:
   resource: "bucket"
   parent: "database"
@@ -31,8 +27,6 @@ replacement:
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
-operation: MongoDB\\Database::selectGridFSBucket
-position: 4
 replacement:
   resource: "bucket"
   parent: "database"
@@ -40,8 +34,6 @@ replacement:
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\Database::selectGridFSBucket
-position: 5
 replacement:
   resource: "bucket"
   parent: "database"

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

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

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 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 to use for converting BSON. Defaults to the original
-  Database's type map.
+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 write concern.
+replacement:
+  resource: "database"
+  parent: "original database"
 ...

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

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

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

@@ -5,9 +5,8 @@ description: |
   The bucket name, which will be used as a prefix for the files and chunks
   collections. Defaults to ``"fs"``.
 interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::__construct
+operation: ~
 optional: true
-position: 1
 ---
 arg_name: option
 name: chunkSizeBytes
@@ -15,15 +14,12 @@ type: integer
 description: |
   The chunk size in bytes. Defaults to ``261120`` (i.e. 255 KiB).
 interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::__construct
+operation: ~
 optional: true
-position: 2
 ---
 source:
   file: apiargs-common-option.yaml
   ref: readConcern
-operation: MongoDB\\GridFS\\Bucket::__construct
-position: 3
 replacement:
   resource: "bucket"
   parent: "database"
@@ -31,8 +27,6 @@ replacement:
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
-operation: MongoDB\\GridFS\\Bucket::__construct
-position: 4
 replacement:
   resource: "bucket"
   parent: "database"
@@ -40,8 +34,6 @@ replacement:
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern
-operation: MongoDB\\GridFS\\Bucket::__construct
-position: 5
 replacement:
   resource: "bucket"
   parent: "database"

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

 source:
   file: apiargs-common-param.yaml
   ref: $manager
-operation: MongoDB\\GridFS\\Bucket::__construct
-position: 1
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $databaseName
-operation: MongoDB\\GridFS\\Bucket::__construct
-position: 2
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\GridFS\\Bucket::__construct
-position: 3
 ...

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

-arg_name: param
-name: $id
-type: mixed
-description: |
-  The ``_id`` of the file to delete.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::delete
-optional: false
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $id
+replacement:
+  resource: " to delete"
 ...

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

-arg_name: param
-name: $id
-type: mixed
-description: |
-  The ``_id`` of the file to download.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::downloadToStream
-optional: false
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $id
+replacement:
+  resource: " to download"
 ---
-arg_name: param
-name: $destination
-type: resource
-description: |
-  Writable stream where the GridFS file's contents will be written.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::downloadToStream
-optional: false
-position: 2
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $destination
 ...

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

-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: MongoDB\\GridFS\\Bucket::downloadToStreamByName
-optional: true
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: revision
 ...

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

-arg_name: param
-name: $filename
-type: string
-description: |
-  The ``filename`` of the file to download.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::downloadToStreamByName
-optional: false
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $filename
+replacement:
+  resource: " to download"
 ---
-arg_name: param
-name: $destination
-type: resource
-description: |
-  Writable stream where the GridFS file's contents will be written.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::downloadToStreamByName
-optional: false
-position: 2
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $destination
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\GridFS\\Bucket::downloadToStreamByName
-position: 3
 ...

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

-arg_name: param
-name: $stream
-type: resource
-description: |
-  The GridFS stream resource.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::getFileDocumentForStream
-optional: false
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $stream
 ...

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

-arg_name: param
-name: $stream
-type: resource
-description: |
-  The GridFS stream resource.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::getFileIdForStream
-optional: false
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $stream
 ...

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

-arg_name: param
-name: $id
-type: mixed
-description: |
-  The ``_id`` of the file to download.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::openDownloadStream
-optional: false
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $id
+replacement:
+  resource: " to download"
 ...

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

-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: MongoDB\\GridFS\\Bucket::openDownloadStreamByName
-optional: true
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: revision
 ...

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

-arg_name: param
-name: $filename
-type: string
-description: |
-  The ``filename`` of the file to download.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::openDownloadStreamByName
-optional: false
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $filename
+replacement:
+  resource: " to download"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\GridFS\\Bucket::openDownloadStreamByName
-position: 2
 ...

docs/includes/apiargs-MongoDBGridFSBucket-method-openUploadStream-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: MongoDB\\GridFS\\Bucket::openUploadStream
-optional: true
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: _id
 ---
-arg_name: option
-name: chunkSizeBytes
-type: integer
-description: |
-  The chunk size in bytes. Defaults to the bucket's ``chunkSizeBytes`` option.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::openUploadStream
-optional: true
-position: 2
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: chunkSizeBytes
 ---
-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: MongoDB\\GridFS\\Bucket::openUploadStream
-optional: true
-position: 3
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: metadata
 ...

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

-arg_name: param
-name: $filename
-type: string
-description: |
-  The ``filename`` of the file to create.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::openUploadStream
-optional: false
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $filename
+replacement:
+  resource: " to create"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\GridFS\\Bucket::openUploadStream
-position: 2
 ...

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

-arg_name: param
-name: $id
-type: mixed
-description: |
-  The ``_id`` of the file to rename.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::rename
-optional: false
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $id
+replacement:
+  resource: " to rename"
 ---
 arg_name: param
 name: $newFilename
@@ -14,7 +10,6 @@ type: string
 description: |
   The new ``filename`` value.
 interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::rename
+operation: ~
 optional: false
-position: 2
 ...

docs/includes/apiargs-MongoDBGridFSBucket-method-uploadFromStream-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: MongoDB\\GridFS\\Bucket::uploadFromStream
-optional: true
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: _id
 ---
-arg_name: option
-name: chunkSizeBytes
-type: integer
-description: |
-  The chunk size in bytes. Defaults to the bucket's ``chunkSizeBytes`` option.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::uploadFromStream
-optional: true
-position: 2
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: chunkSizeBytes
 ---
-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: MongoDB\\GridFS\\Bucket::uploadFromStream
-optional: true
-position: 3
+source:
+  file: apiargs-MongoDBGridFSBucket-common-option.yaml
+  ref: metadata
 ...

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

-arg_name: param
-name: $filename
-type: string
-description: |
-  The ``filename`` of the file to create.
-interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::uploadFromStream
-optional: false
-position: 1
+source:
+  file: apiargs-MongoDBGridFSBucket-common-param.yaml
+  ref: $filename
+replacement:
+  resource: " to create"
 ---
 arg_name: param
 name: $source
 type: resource
 description: |
-  Readable stream where the file's contents will be read.
+  Readable stream, from which the new GridFS file's contents will be read.
 interface: phpmethod
-operation: MongoDB\\GridFS\\Bucket::uploadFromStream
+operation: ~
 optional: false
-position: 2
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\GridFS\\Bucket::uploadFromStream
-position: 3
 ...

docs/includes/apiargs-common-option.yaml

 arg_name: option
+name: maxTimeMS
+type: integer
+description: |
+   The cumulative time limit in milliseconds for processing operations on the
+   cursor. MongoDB aborts the operation at the earliest following
+   :term:`interrupt point`.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
 name: readConcern
 type: :php:`MongoDB\\Driver\\ReadConcern <class.mongodb-driver-readconcern>`
 description: |
@@ -7,35 +18,34 @@ description: |
 interface: phpmethod
 operation: selectCollection
 optional: true
-position: 1
 replacement:
   resource: "collection"
   parent: "client"
 ---
 arg_name: option
+name: readPreference
+type: :php:`MongoDB\\Driver\\ReadPreference <class.mongodb-driver-readpreference>`
 description: |
   The default read preference to use for {{resource}} operations. Defaults to
   the {{parent}}'s read preference.
 interface: phpmethod
-name: readPreference
-operation: selectCollection
+operation: ~
 optional: true
-position: 2
-type: :php:`MongoDB\\Driver\\ReadPreference <class.mongodb-driver-readpreference>`
 replacement:
   resource: "collection"
   parent: "client"
 ---
 arg_name: option
+name: typeMap
+type: array
 description: |
-  Default type map for cursors and BSON documents. Defaults to the
-  {{parent}}'s type map.
+  The :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. Defaults to the {{parent}}'s type map.
 interface: phpmethod
-name: typeMap
-operation: selectCollection
+operation: ~
 optional: true
-position: 3
-type: array
 replacement:
   parent: "client"
 ---
@@ -46,51 +56,9 @@ description: |
   The default write concern to use for {{resource}} operations. Defaults
   to the {{parent}}'s write concern.
 interface: phpmethod
-operation: selectCollection
+operation: ~
 optional: true
-position: 4
 replacement:
   resource: "collection"
   parent: "client"
----
-arg_name: option
-name: maxTimeMS
-description: |
-   The cumulative time limit in milliseconds for processing operations on
-   the cursor. MongoDB aborts the operation at the earliest following
-   :term:`interrupt point`.
-interface: phpmethod
-operation: listDatabases
-type: integer
-optional: true
-position: 5
----
-arg_name: option
-name: bypassDocumentValidation
-type: boolean
-description: |
-  If ``true``, allows the write operation to circumvent document level
-  validation. This only applies when using the :pipeline:`$out` stage.
-
-  Document validation requires MongoDB v3.2 or later: if you are using
-  an earlier version of MongoDB, this option will be ignored.
-interface: phpmethod
-operation: aggregate
-optional: true
-position: 6
----
-arg_name: option
-name: upsert
-type: boolean
-description: |
-  When true, {{role}} creates a new document if no document
-  matches the query. If a document matches the query, {{role}}
-  performs an update. To avoid multiple upserts, ensure that the query
-  fields are uniquely indexed.
-
-  The default is ``false``.
-optional: true
-interface: phpmethod
-operation: MongoDB\\Collection::findOneAndUpdate
-position: 7
 ...

docs/includes/apiargs-common-param.yaml

@@ -7,7 +7,6 @@ description: |
 interface: phpmethod
 operation: ~
 optional: false
-position: 1
 ---
 arg_name: param
 name: $databaseName
@@ -19,7 +18,6 @@ operation: ~
 optional: false
 replacement:
   action: ""
-position: 1
 ---
 arg_name: param
 name: $collectionName
@@ -31,7 +29,6 @@ operation: ~
 optional: false
 replacement:
   action: ""
-position: 2
 ---
 arg_name: param
 name: $options
@@ -41,17 +38,4 @@ description: |
 interface: phpmethod
 operation: ~
 optional: true
-position: 3
----
-arg_name: param
-name: $filter
-type: array|object
-description: |
-  The filter criteria that specifies the documents to {{verb}}.
-interface: phpmethod
-operation: ~
-optional: false
-position: 4
-replacement:
-  verb: "count"
 ...

docs/reference/method/MongoDBCollection-createIndex.txt

@@ -26,7 +26,7 @@ Definition
    .. 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:
+   version supports. MongoDB includes the following options:
 
    .. include:: /includes/apiargs/MongoDBCollection-method-createIndex-option.rst
 

docs/reference/method/MongoDBCollection-createIndexes.txt

@@ -19,37 +19,40 @@ Definition
 
    .. code-block:: php
 
-      function createIndexes(array $indexes): string[]
+      function createIndexes(array $indexes, array $options = []): string[]
 
-   ``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()`.
+   :phpmethod:`MongoDB\\Collection::createIndexes()` has the following
+   parameters:
 
-   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::
+   .. include:: /includes/apiargs/MongoDBCollection-method-createIndexes-param.rst
 
-      [
-          [ 'key' => [ 'username' => 1 ], 'unique' => true ],
-          [ 'key' => [ 'loc' => '2dsphere' ], 'name' => 'geo_index' ],
-      ]
+   The ``$options`` parameter supports the following options:
 
-   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.
+   .. include:: /includes/apiargs/MongoDBCollection-method-createIndexes-option.rst
 
    :returns:
 
       The names of the created indexes as an array of strings.
 
+``$indexes`` parameter
+----------------------
+
+The ``$indexes`` parameter is an array of index specification documents. Each
+element in ``$indexes`` must itself be an array or object with a ``key`` field,
+which corresponds to the ``$key`` parameter of :phpmethod:`createIndex()
+<MongoDB\\Collection::createIndex()>`. The array or object may include other
+fields that correspond to index options accepted by :phpmethod:`createIndex()
+<MongoDB\\Collection::createIndex()>` (excluding ``writeConcern``).
+
+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::
+
+   [
+       [ 'key' => [ 'username' => 1 ], 'unique' => true ],
+       [ 'key' => [ 'loc' => '2dsphere' ], 'name' => 'geo_index' ],
+   ]
+
 Example
 -------