Update MongoDB\Collection documentation

Author: jmikola

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

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

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

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

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

@@ -1,30 +1,31 @@
 source:
-  ref: bypassDocumentValidation
   file: apiargs-common-option.yaml
+  ref: bypassDocumentValidation
 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
+optional: true
 position: 2
 ---
 source:
-  ref: writeConcern
   file: apiargs-common-option.yaml
+  ref: writeConcern
 operation: MongoDB\\Collection::bulkWrite
 replacement:
   resource: "write"
+  parent: "collection"
 position: 3
 ...

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

@@ -2,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 ] ],
@@ -22,18 +23,19 @@ description: |
          [ 'updateOne'  => [ $filter, $update, $options ] ],
      ]
 post: |
-  Arguments correspond to the respective operation methods. However,
-  the ``writeConcern`` option is specified for the top-level bulk write
-  operation instead of each individual operation.
+  Arguments correspond to the respective operation methods. However, the
+  ``writeConcern`` option is specified as a top-level option to
+  :phpmethod:`MongoDB\\Collection::bulkWrite()` instead of each individual
+  operation.
 interface: phpmethod
 operation: MongoDB\\Collection::bulkWrite
 optional: true
 position: 1
 ---
 source:
-  ref: $options
   file: apiargs-common-param.yaml
+  ref: $options
 operation: MongoDB\\Collection::bulkWrite
 interface: phpmethod
 position: 2
-...
+...

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

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

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

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

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

@@ -1,27 +1,27 @@
 arg_name: option
 name: hint
-type: string or array|object
+type: string|array|object
 description: |
-  The index to use. If you specify a document, it is interpreted as
-  an index specification and a name will be generated.
-optional: true
+  The index to use. If you specify a document, it is interpreted as an index
+  specification and a name will be generated.
 interface: phpmethod
 operation: MongoDB\\Collection::count
+optional: true
 position: 1
 ---
 arg_name: option
 name: limit
 type: integer
 description: |
   The maximum number of documents to return.
-optional: true
 interface: phpmethod
 operation: MongoDB\\Collection::count
+optional: true
 position: 2
 ---
 source:
-  ref: maxTimeMS
   file: apiargs-common-option.yaml
+  ref: maxTimeMS
 operation: MongoDB\\Collection::count
 position: 3
 ---
@@ -31,22 +31,24 @@ source:
 operation: MongoDB\\Collection::count
 replacement:
   resource: "count"
+  parent: "collection"
 position: 4
 ---
 source:
   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.
-optional: true
 interface: phpmethod
 operation: MongoDB\\Collection::count
+optional: true
 position: 6
 ...

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

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