Refactor option/param includes and document MongoDB 3.4 features

Author: jmikola

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

@@ -1,8 +1,19 @@
 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

@@ -1,14 +1,10 @@
 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

@@ -1,8 +1,6 @@
 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

@@ -1,5 +1,4 @@
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS
-operation: MongoDB\\Client::listDatabases
 ...

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

@@ -1,6 +1,4 @@
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Client::listDatabases
-position: 1
 ...

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

@@ -1,22 +1,16 @@
 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

@@ -1,14 +1,10 @@
 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

@@ -0,0 +1,79 @@
+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

@@ -0,0 +1,31 @@
+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
 ...