Update MongoDB\Client documentation

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

+arg_name: option
+name: typeMap
+type: array
+description: |
+  Default :php:`type map
+  <manual/en/mongodb.persistence.deserialization.php#mongodb.persistence.typemaps>`
+  to apply to cursors. 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\\Client::__construct
+optional: true
+position: 1
+...

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

@@ -2,11 +2,11 @@ arg_name: param
 name: $uri
 type: string
 description: |
-  The URI of the standalone, replica set, or sharded cluster to which to connect. Refer
-  to the :manual:`MongoDB connection string reference </reference/connection-string>`
-  for formatting.
+  The URI of the standalone, replica set, or sharded cluster to which to
+  connect. Refer to the :manual:`MongoDB connection string reference
+  </reference/connection-string>` for formatting.
 
-  Defaults to ``mongodb://localhost:27017`` if unspecified.
+  Defaults to ``mongodb://127.0.0.1:27017`` if unspecified.
 interface: phpmethod
 operation: MongoDB\\Client::__construct
 optional: true
@@ -16,15 +16,14 @@ arg_name: param
 name: $uriOptions
 type: array
 description: |
-  Specifies additional URI options, such as authentication credentials
-  or query string parameters. The options specified in ``$uriOptions``
-  take precedence over any analogous options present in the
-  ``$uri`` string.
+  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 options.
+  <mongodb-driver-manager.construct>` extension reference and :manual:`MongoDB
+  connection string </reference/connection-string>` documentation for valid
+  options.
 interface: phpmethod
 operation: MongoDB\\Client::__construct
 optional: true
@@ -34,12 +33,11 @@ arg_name: param
 name: $driverOptions
 type: array
 description: |
-  Specify driver-specific options. In addition to any
-  options supported by the :php:`extension <mongodb-driver-manager>`,
-  the |php-library| allows you to specify a default ``typeMap`` to
-  apply to the cursors it creates. Refer to the driver's
-  :php:`Persistence documentation <mongodb-persistence>` for more
-  about type maps.
+  Specify driver-specific options, such as SSL options. In addition to any
+  options supported by the :php:`extension <mongodb-driver-manager>`, the
+  |php-library| allows you to specify a default :php:`type map
+  <manual/en/mongodb.persistence.deserialization.php#mongodb.persistence.typemaps>`
+  to apply to the cursors it creates.
 interface: phpmethod
 operation: MongoDB\\Client::__construct
 optional: true

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

-arg_name: option
-interface: phpmethod
-operation: MongoDB\\Client::dropDatabase
 source:
   file: apiargs-common-option.yaml
   ref: typeMap
-position: 1
+operation: MongoDB\\Client::dropDatabase
+description: |
+  Type map for BSON deserialization. This will be used for the returned command
+  result document. Defaults to the clients's type map.
 ...

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

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

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

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

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

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

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

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

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

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

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

+source:
+  file: apiargs-common-param.yaml
+  ref: $databaseName
+operation: MongoDB\\Client::selectCollection
+position: 1
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $collectionName
+operation: MongoDB\\Client::selectCollection
+position: 2
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+operation: MongoDB\\Client::selectCollection
+position: 3
+...

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

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

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

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

docs/includes/apiargs-common-option.yaml

@@ -2,19 +2,20 @@ arg_name: option
 name: readConcern
 type: :php:`MongoDB\\Driver\\ReadConcern <class.mongodb-driver-readconcern>`
 description: |
-  The default read concern to use for {{resource}} operations. Defaults
-  to the Client's specified read concern.
+  The default read concern to use for {{resource}} operations. Defaults to the
+  {{parent}}'s read concern.
 interface: phpmethod
 operation: selectCollection
 optional: true
 position: 1
 replacement:
   resource: "collection"
+  parent: "client"
 ---
 arg_name: option
 description: |
-  The default read preference to use for {{resource}} operations.
-  Defaults to the {{parent}}'s read preference.
+  The default read preference to use for {{resource}} operations. Defaults to
+  the {{parent}}'s read preference.
 interface: phpmethod
 name: readPreference
 operation: selectCollection
@@ -23,7 +24,7 @@ position: 2
 type: :php:`MongoDB\\Driver\\ReadPreference <class.mongodb-driver-readpreference>`
 replacement:
   resource: "collection"
-  parent: "Client"
+  parent: "client"
 ---
 arg_name: option
 description: |
@@ -36,21 +37,21 @@ optional: true
 position: 3
 type: array
 replacement:
-  parent: "Client"
+  parent: "client"
 ---
 arg_name: option
 name: writeConcern
 type: :php:`MongoDB\\Driver\\WriteConcern <class.mongodb-driver-writeconcern>`
 description: |
   The default write concern to use for {{resource}} operations. Defaults
-  to the {{parent}}'s specified write concern.
+  to the {{parent}}'s write concern.
 interface: phpmethod
 operation: selectCollection
 optional: true
 position: 4
 replacement:
   resource: "collection"
-  parent: "Client"
+  parent: "client"
 ---
 arg_name: option
 name: maxTimeMS

docs/reference/method/MongoDBClient-dropDatabase.txt

@@ -13,26 +13,27 @@ MongoDB\\Client::dropDatabase()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Client::dropDatabase($databaseName, $options)
+.. phpmethod:: MongoDB\\Client::dropDatabase()
 
-   Drop a MongoDB database.
+   Drop a database on the server.
 
    .. code-block:: php
 
-      function dropDatabase($databaseName, array $options [])
+      function dropDatabase($databaseName, array $options []): array|object
 
-   :phpmethod:`MongoDB\\Client::dropDatabase` has the following parameters:
+   :phpmethod:`MongoDB\\Client::dropDatabase()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBClient-method-dropDatabase-param.rst
 
-   ``dropDatabase`` supports the following values for the ``$options`` array:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBClient-method-dropDatabase-option.rst
 
-Output
-------
+   :returns:
 
-Returns an array or object containing the result document.
+      An array or object with the result document of the :manual:`dropDatabase
+      </reference/command/dropDatabase>` command. The return type will depend on
+      the ``typeMap`` option.
 
 Example
 -------
@@ -49,9 +50,7 @@ The following example drops the ``demo`` database:
 
    var_dump($result);
 
-The ``dropDatabase`` operation would return an object similar to:
-
-.. code-block:: php
+The output would then resemble::
 
    object(MongoDB\Model\BSONDocument)#8 (1) {
      ["storage":"ArrayObject":private]=>
@@ -65,6 +64,6 @@ The ``dropDatabase`` operation would return an object similar to:
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Client::drop`
-   - :manual:`dropDatabase() command reference
-     </reference/command/dropDatabase>` in the MongoDB manual.
+   - :phpmethod:`MongoDB\\Database::drop()`
+   - :manual:`dropDatabase </reference/command/dropDatabase>` command reference
+     in the MongoDB manual

docs/reference/method/MongoDBClient-listDatabases.txt

@@ -13,28 +13,27 @@ MongoDB\\Client::listDatabases()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Client::listDatabases($options)
+.. phpmethod:: MongoDB\\Client::listDatabases()
 
-   Lists the available databases.
+   Returns information for all databases on the server.
 
    .. code-block:: php
 
       function listDatabases(array $options = []): MongoDB\Model\DatabaseInfoIterator
 
-   :phpmethod:`MongoDB\\Client::listDatabases` has the following parameters:
+   :phpmethod:`MongoDB\\Client::listDatabases()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBClient-method-listDatabases-param.rst
 
-   ``listDatabases`` supports the following values for the ``$options`` array:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBClient-method-listDatabases-option.rst
 
-Output
-------
+   :returns:
 
-Information for all databases on the :program:`mongod`, replica set,
-or sharded cluster to which you are connected. The returned elements are
-``MongoDB\Model\DatabaseInfo`` objects.
+      A traversable :phpclass:`MongoDB\\Model\DatabaseInfoIterator`, which
+      contains an :phpclass:`MongoDB\\Model\DatabaseInfo` object for each
+      database on the server.
 
 Example
 -------
@@ -51,9 +50,7 @@ The following example lists all databases on the server:
        var_dump($databaseInfo);
    }
 
-The above example would output something similar to:
-
-.. code-block:: php
+The output would then resemble::
 
    object(MongoDB\Model\DatabaseInfo)#4 (3) {
      ["name"]=>
@@ -74,5 +71,5 @@ The above example would output something similar to:
 
 .. seealso::
 
-   :manual:`listDatabases() command reference in the MongoDB
-   manual </reference/command/listDatabases>`
+   - :manual:`listDatabases </reference/command/listDatabases>` command
+     reference in the MongoDB manual

docs/reference/method/MongoDBClient-selectCollection.txt

@@ -13,35 +13,37 @@ MongoDB\\Client::selectCollection()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Client::selectCollection($databaseName, $collectionName, $options)
+.. phpmethod:: MongoDB\\Client::selectCollection()
 
-   Selects a collection on the :program:`mongod` to which your application
-   is connected.
+   Selects a collection on the server.
 
    .. code-block:: php
 
-      function selectCollection($databaseName, $collectionName, array $options = [])
+      function selectCollection($databaseName, $collectionName, array $options = []): MongoDB\Collection
 
-   :phpmethod:`MongoDB\\Client::selectCollection` has the following parameters:
+   :phpmethod:`MongoDB\\Client::selectCollection()` has the following parameters:
 
-   .. include:: /includes/apiargs/common-param.rst
+   .. include:: /includes/apiargs/MongoDBClient-method-selectCollection-param.rst
 
-   The following table describes the options that
-   :phpmethod:`MongoDB\\Client::selectCollection` can accept.
+   The ``$options`` parameter supports the following options:
 
-   .. include:: /includes/apiargs/common-option.rst
+   .. include:: /includes/apiargs/MongoDBClient-method-selectCollection-option.rst
 
-Output
-------
+   :returns:
 
-Returns a :phpclass:`MongoDB\\Collection` object.
+      A :phpclass:`MongoDB\\Collection` object.
+
+Behavior
+--------
+
+The selected collection inherits options such as read preference and type
+mapping from the :phpclass:`Client <MongoDB\\Client>` object. Options may be
+overridden via the ``$options`` parameter.
 
 Example
 -------
 
-
-The following example selects the ``users`` collection in the ``demo``
-database:
+The following example selects the ``users`` collection in the ``demo`` database:
 
 .. code-block:: php
 
@@ -51,11 +53,13 @@ database:
 
    $collection = $client->selectCollection('demo', 'users');
 
-The following examples selects the ``users`` collection in the ``demo``
-database with a custom read preference:
+The following example selects the ``users`` collection in the ``demo`` database
+with a custom read preference:
 
 .. code-block:: php
 
+   <?php
+
    $client = new MongoDB\Client;
 
    $collection = $client->selectCollection(
@@ -68,5 +72,5 @@ database with a custom read preference:
 
 .. seealso::
 
-   - :phpmethod:`Collection::__construct`
-   - :phpmethod:`MongoDB\\Client::__get`
+   - :phpmethod:`MongoDB\\Collection::__construct()`
+   - :phpmethod:`MongoDB\\Database::selectCollection()`

docs/reference/method/MongoDBClient-selectDatabase.txt

@@ -13,28 +13,32 @@ MongoDB\\Client::selectDatabase()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Client::selectDatabase($databaseName, $options)
+.. phpmethod:: MongoDB\\Client::selectDatabase()
 
-   Selects a database on the :program:`mongod` instance to which your
-   application is connected.
+   Selects a database on the server.
 
    .. code-block:: php
 
-      function selectDatabase($databaseName array $options = []): MongoDB\Database
+      function selectDatabase($databaseName, array $options = []): MongoDB\Database
 
-   :phpmethod:`MongoDB\\Client::selectDatabase` has the following parameters:
+   :phpmethod:`MongoDB\\Client::selectDatabase()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBClient-method-selectDatabase-param.rst
 
-   The following table describes the options that
-   :phpmethod:`MongoDB\\Client::selectDatabase` can accept.
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBClient-method-selectDatabase-option.rst
 
-Output
-------
+   :returns:
 
-Returns a :phpclass:`MongoDB\\Database` object.
+      A :phpclass:`MongoDB\\Database` object.
+
+Behavior
+--------
+
+The selected database inherits options such as read preference and type mapping
+from the :phpclass:`Client <MongoDB\\Client>` object. Options may be overridden
+via the ``$options`` parameter.
 
 Example
 -------
@@ -67,5 +71,5 @@ preference:
 
 .. seealso::
 
-   - :phpmethod:`Collection::__construct`
-   - :phpmethod:`MongoDB\\Client::__get`
+   - :phpmethod:`MongoDB\\Client::__get()`
+   - :phpmethod:`MongoDB\\Database::__construct()`

docs/reference/method/MongoDBClient__construct.txt

@@ -4,7 +4,6 @@ MongoDB\\Client::__construct()
 
 .. default-domain:: mongodb
 
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -14,26 +13,28 @@ MongoDB\\Client::__construct()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Client::__construct($uri, $uriOptions, $driverOptions)
+.. phpmethod:: MongoDB\\Client::__construct()
 
    Constructs a new :phpclass:`Client <MongoDB\\Client>` instance.
 
    .. code-block:: php
 
-      function __construct($uri = 'mongodb://localhost:27017', array $uriOptions = [], array $driverOptions = [])
+      function __construct($uri = 'mongodb://127.0.0.1/', array $uriOptions = [], array $driverOptions = [])
 
-   :phpmethod:`MongoDB\\Client::__construct` has the following parameters:
+   :phpmethod:`MongoDB\\Client::__construct()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBClient-method-construct-param.rst
 
+   The ``$driverOptions`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBClient-method-construct-driverOptions.rst
+
 Examples
 --------
 
-If you do not specify a ``$uri`` value, the driver connects to a
-standalone :program:`mongod` on ``localhost`` via port ``27017``. The
-following example demonstrates how to connect to a replica set
-with a custom
-read preference:
+If you do not specify a ``$uri`` value, the driver connects to a standalone
+:program:`mongod` on ``127.0.0.1`` via port ``27017``. The following example
+demonstrates how to connect to a replica set with a custom read preference:
 
 .. code-block:: php
 
@@ -42,15 +43,15 @@ read preference:
    $client = new MongoDB\Client(
        'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet',
        [
-           'readPreference' => 'secondaryPreferred'
+           'readPreference' => 'secondaryPreferred',
        ]
    );
 
 By default, the |php-library| deserializes BSON documents and arrays
-as ``MongoDB\Model\BSONDocument`` and ``MongoDB\Model\BSONArray``
-objects, respectively. The following example demonstrates how to
-have the library unserialize everything as a PHP array, as was done
-in the legacy :php:`mongo extension <mongo>`.
+as :phpclass:`MongoDB\\Model\\BSONDocument` and
+:phpclass:`MongoDB\\Model\\BSONArray` objects, respectively. The following
+example demonstrates how to have the library unserialize everything as a PHP
+array, as was done in the legacy :php:`mongo extension <mongo>`.
 
 .. code-block:: php
 
@@ -59,8 +60,16 @@ in the legacy :php:`mongo extension <mongo>`.
    $client = new MongoDB\Client(
        null,
        [],
-       [ 'typeMap' => [
-           'root' => 'array', 'document' => 'array', 'array' => 'array'
+       [
+           'typeMap' => [
+               'root' => 'array',
+               'document' => 'array',
+               'array' => 'array',
            ],
        ]
    );
+
+.. seealso::
+
+   - :php:`MongoDB\\Driver\\Manager::__construct()
+     <mongodb-driver-manager.construct>`

docs/reference/method/MongoDBClient__get.txt

@@ -4,7 +4,6 @@ MongoDB\\Client::__get()
 
 .. default-domain:: mongodb
 
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -14,39 +13,43 @@ MongoDB\\Client::__get()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Client::__get($databaseName)
+.. phpmethod:: MongoDB\\Client::__get()
 
-   Select a MongoDB database.
+   Selects a database on the server. This :php:`magic method <oop5.magic>` is
+   an alias for the :phpmethod:`selectDatabase()
+   <MongoDB\\Client::selectDatabase>` method.
 
    .. code-block:: php
 
       function __get($databaseName): MongoDB\Database
 
-   :phpmethod:`MongoDB\\Client::__get` has the following parameters:
+   :phpmethod:`MongoDB\\Client::__get()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBClient-method-get-param.rst
 
+   :returns:
+
+      A :phpclass:`MongoDB\\Database` object.
+
 Behavior
 --------
 
-The selected database inherits options such as read preference and
-type mapping from the :phpclass:`Client <MongoDB\\Client>` object.
-If you wish to override any options, use the 
-:phpmethod:`MongoDB\\Client::selectDatabase` method.
+The selected database inherits options such as read preference and type mapping
+from the :phpclass:`Client <MongoDB\\Client>` object. If you wish to override
+any options, use the :phpmethod:`MongoDB\\Client::selectDatabase` method.
 
 .. note::
 
    To select databases whose names contain special characters, such as
    ``-``, use complex syntax, as in ``$client->{'that-database'}``.
 
-   Alternatively, :phpmethod:`MongoDB\\Client::selectDatabase` supports
+   Alternatively, :phpmethod:`MongoDB\\Client::selectDatabase()` supports
    selecting databases whose names contain special characters.
 
 Examples
 --------
 
-The following example selects the ``demo`` and ``another-app``
-databases:
+The following example selects the ``demo`` and ``another-app`` databases:
 
 .. code-block:: php
 
@@ -59,5 +62,6 @@ databases:
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Client::selectDatabase`
-   - :php:`Property Overloading <oop5.overloading>` in the PHP Manual.
+   - :phpmethod:`MongoDB\\Client::selectDatabase()`
+   - :phpmethod:`MongoDB\\Database::__construct()`
+   - :php:`Property Overloading <oop5.overloading>` in the PHP Manual