Update MongoDB\Database documentation

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

@@ -3,10 +3,18 @@ source:
   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.
 ---
 source:
   file: apiargs-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

 arg_name: param
 name: $command
-type: string
+type: array|object
 description: |
-  The name of the :manual:`database command </reference/command>`
-  to execute.
+  The :manual:`database command </reference/command>` document.
 interface: phpmethod
 operation: MongoDB\\Database::command
 optional: false

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

@@ -3,17 +3,39 @@ source:
   ref: readConcern
 operation: MongoDB\\Database::__construct
 position: 1
+replacement:
+  resource: "database"
+  parent: "manager"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
 operation: MongoDB\\Database::__construct
 position: 2
+replacement:
+  resource: "database"
+  parent: "manager"
 ---
-source:
-  file: apiargs-common-option.yaml
-  ref: typeMap
+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:
@@ -21,4 +43,7 @@ source:
   ref: writeConcern
 operation: MongoDB\\Database::__construct
 position: 4
-...
+replacement:
\ No newline at end of file
+  resource: "database"
+  parent: "manager"
+...

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

@@ -5,8 +5,8 @@ operation: MongoDB\\Database::__construct
 position: 1
 ---
 source:
-  ref: $databaseName
   file: apiargs-common-param.yaml
+  ref: $databaseName
 operation: MongoDB\\Database::__construct
 position: 2
 ---
@@ -14,5 +14,5 @@ source:
   ref: $options
   file: apiargs-common-param.yaml
 operation: MongoDB\\Database::__construct
-position: 2
-...
+position: 3
+...
\ No newline at end of file

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

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

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

 source:
   file: apiargs-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Database::dropCollection
+operation: MongoDB\\Database::drop
 position: 1
-...
+description: |
\ No newline at end of file
+  Type map for BSON deserialization. This will be used for the returned command
+  result document. Defaults to the database's type map.
+...

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

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

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

@@ -3,4 +3,7 @@ source:
   ref: typeMap
 operation: MongoDB\\Database::dropCollection
 position: 1
-...
+description: |
\ No newline at end of file
+  Type map for BSON deserialization. This will be used for the returned command
+  result document. Defaults to the database's type map.
+...

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

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

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

@@ -3,4 +3,6 @@ source:
   ref: $collectionName
 operation: MongoDB\\Database::__get
 position: 1
-...
+replacement:
\ No newline at end of file
+  action: " to select"
+...

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

-source:
-  file: apiargs-common-option.yaml
-  ref: readConcern
+arg_name: option
+name: filter
+type: array|object
+description: |
+  Query by which to filter collections.
+interface: phpmethod
 operation: MongoDB\\Database::listCollections
+optional: true
 position: 1
 ---
 source:
   file: apiargs-common-option.yaml
-  ref: readPreference
+  ref: maxTimeMS
 operation: MongoDB\\Database::listCollections
 position: 2
----
-source:
-  file: apiargs-common-option.yaml
-  ref: typeMap
-operation: MongoDB\\Database::listCollections
-position: 3
----
-source:
-  file: apiargs-common-option.yaml
-  ref: writeConcern
-operation: MongoDB\\Database::listCollections
-position: 4
-...
+...
\ No newline at end of file

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

@@ -3,5 +3,4 @@ source:
   ref: $options
 operation: MongoDB\\Database::listCollections
 position: 1
-optional: true
-...
+...
\ No newline at end of file

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

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

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

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

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

@@ -3,30 +3,30 @@ source:
   ref: readConcern
 operation: MongoDB\\Database::withOptions
 description: |
-  The default read concern to use for database operations. Defaults
-  to the original Databases's specified read concern.
+  The default read concern to use for database operations. Defaults to the
+  original Databases's read concern.
 ---
 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.
+  The default read preference to use for database operations. Defaults to the
+  original Database's read preference.
 ---
 source:
   file: apiargs-common-option.yaml
   ref: typeMap
 operation: MongoDB\\Database::withOptions
 description: |
-  Default type map for cursors and BSON documents. Defaults to the
-  original Database's type map value.
+  Default type map to use for converting BSON. Defaults to the original
+  Database's type map.
 ---
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern
 operation: MongoDB\\Database::withOptions
 description: |
-  The default write concern to use for database operations. Defaults
-  to the original Database's specified write concern.
-...
+  The default write concern to use for database operations. Defaults to the
+  original Database's write concern.
+...
\ No newline at end of file

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

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

docs/reference/class/MongoDBDatabase.txt

@@ -44,8 +44,8 @@ Methods
 .. toctree::
    :titlesonly:
 
-   /reference/method/MongoDBDatabase__get
    /reference/method/MongoDBDatabase__construct
+   /reference/method/MongoDBDatabase__get
    /reference/method/MongoDBDatabase-command
    /reference/method/MongoDBDatabase-createCollection
    /reference/method/MongoDBDatabase-drop

docs/reference/method/MongoDBDatabase-command.txt

@@ -13,113 +13,136 @@ MongoDB\\Database::command()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::command
+.. phpmethod:: MongoDB\\Database::command()
 
    Execute a :manual:`command </reference/command>` on the database.
-   
+
    .. code-block:: php
-                   
+
       function command($command, array $options = []): MongoDB\Driver\Cursor
 
-   :phpmethod:`MongoDB\\Database::command` has the following parameters:
+   :phpmethod:`MongoDB\\Database::command()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-command-param.rst
-   
-   ``command`` supports the following options:
-   
+
+   The ``$options`` parameter supports the following options:
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-command-option.rst
 
+   :returns:
+
+      A :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>` object.
+
 Example
 -------
 
-The following operation creates a new user in the database using
-the :dbcommand:`createUser` command:
+The following example executes an :manual:`isMaster
+</reference/command/isMaster>` command, which returns a cursor with a single
+result document:
 
 .. code-block:: php
 
-   $database = (new MongoDB\Client)->example;
+   <?php
 
-   $newUser = $database->command(
-       [
-           'createUser' => 'admin',
-           'pwd' => 'admin123',
-           'roles' => [
-               'readWrite'
-           ]
-       ]
-   );
+   $database = (new MongoDB\Client)->example;
 
-   
+   $cursor = $database->command(['isMaster' => 1]);
 
-   var_dump($newUser);
+   var_dump($c->toArray()[0]);
 
 The output would resemble::
-  
-  object(MongoDB\Driver\Cursor)#10 (2) {
-     ["cursor"]=>
-     array(17) {
-       ["stamp"]=>
-       int(0)
-       ["is_command"]=>
-       bool(true)
-       ["sent"]=>
+
+   object(MongoDB\Model\BSONDocument)#11 (1) {
+     ["storage":"ArrayObject":private]=>
+     array(8) {
+       ["ismaster"]=>
        bool(true)
-       ["done"]=>
-       bool(false)
-       ["end_of_event"]=>
-       bool(false)
-       ["in_exhaust"]=>
-       bool(false)
-       ["has_fields"]=>
-       bool(false)
-       ["query"]=>
-       object(stdClass)#9 (3) {
-         ["createUser"]=>
-         string(5) "admin"
-         ["pwd"]=>
-         string(8) "admin123"
-         ["roles"]=>
-         array(1) {
-           [0]=>
-           string(9) "readWrite"
-         }
+       ["maxBsonObjectSize"]=>
+       int(16777216)
+       ["maxMessageSizeBytes"]=>
+       int(48000000)
+       ["maxWriteBatchSize"]=>
+       int(1000)
+       ["localTime"]=>
+       object(MongoDB\BSON\UTCDateTime)#3 (1) {
+         ["milliseconds"]=>
+         string(13) "1477608046464"
        }
-       ["fields"]=>
-       object(stdClass)#3 (0) {
+       ["maxWireVersion"]=>
+       int(4)
+       ["minWireVersion"]=>
+       int(0)
+       ["ok"]=>
+       float(1)
+     }
+   }
+
+The following example executes a :manual:`listCollections
+</reference/command/listCollections>` command, which returns a cursor with
+multiple result documents:
+
+.. code-block:: php
+
+   <?php
+
+   $database = (new MongoDB\Client)->example;
+
+   $cursor = $database->command(['isMaster' => 1]);
+
+   var_dump($c->toArray());
+
+The output would resemble::
+
+   array(3) {
+     [0]=>
+     object(MongoDB\Model\BSONDocument)#11 (1) {
+       ["storage":"ArrayObject":private]=>
+       array(2) {
+         ["name"]=>
+         string(11) "restaurants"
+         ["options"]=>
+         object(MongoDB\Model\BSONDocument)#3 (1) {
+           ["storage":"ArrayObject":private]=>
+           array(0) {
+           }
+         }
        }
-       ["read_preference"]=>
+     }
+     [1]=>
+     object(MongoDB\Model\BSONDocument)#13 (1) {
+       ["storage":"ArrayObject":private]=>
        array(2) {
-         ["mode"]=>
-         int(1)
-         ["tags"]=>
-         array(0) {
+         ["name"]=>
+         string(5) "users"
+         ["options"]=>
+         object(MongoDB\Model\BSONDocument)#12 (1) {
+           ["storage":"ArrayObject":private]=>
+           array(0) {
+           }
          }
        }
-       ["flags"]=>
-       int(0)
-       ["skip"]=>
-       int(0)
-       ["limit"]=>
-       int(1)
-       ["count"]=>
-       int(1)
-       ["batch_size"]=>
-       int(0)
-       ["ns"]=>
-       string(12) "example.$cmd"
-       ["current_doc"]=>
-       object(stdClass)#8 (1) {
-         ["ok"]=>
-         float(1)
+     }
+     [2]=>
+     object(MongoDB\Model\BSONDocument)#15 (1) {
+       ["storage":"ArrayObject":private]=>
+       array(2) {
+         ["name"]=>
+         string(6) "restos"
+         ["options"]=>
+         object(MongoDB\Model\BSONDocument)#14 (1) {
+           ["storage":"ArrayObject":private]=>
+           array(0) {
+           }
+         }
        }
      }
-     ["server_id"]=>
-     int(1)
    }
 
 .. seealso::
-   
+
    - :doc:`/tutorial/commands`
    - :manual:`Database Commands </reference/command>` in the
      MongoDB manual
-     
+   - :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>`
+   - :php:`MongoDB\\Driver\\Manager::executeCommand()
+     <manual/en/mongodb-driver-manager.executecommand.php>`

docs/reference/method/MongoDBDatabase-createCollection.txt

@@ -13,45 +13,45 @@ MongoDB\\Database::createCollection()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::createCollection
+.. phpmethod:: MongoDB\\Database::createCollection()
 
    Explicitly creates a collection.
-   
+
    .. code-block:: php
 
       function createCollection($collectionName, array $options = []): array|object
-   
-   MongoDB creates collections implicitly when you first reference
-   the collection in a command, such as when inserting a document
-   into a new collection. You may also explicitly create a collection
-   with specific options using the ``createCollection()``
-   method, or using :dbcommand:`create` in the :program:`mongo` shell.
-   
+
+   MongoDB creates collections implicitly when you first reference the
+   collection in a command, such as when inserting a document into a new
+   collection. You may also explicitly create a collection with specific options
+   using the :phpmethod:`MongoDB\\Database::createCollection()` method, or using
+   :manual:`db.createCollection() </reference/method/db.createCollection/>` in
+   the :program:`mongo` shell.
+
    Explicitly creating collections enables you to create
    :manual:`capped collections </core/capped-collections>`, specify
    :manual:`document validation criteria </core/document-validation>`,
    or configure your storage engine or indexing options.
-   
-   :phpmethod:`MongoDB\\Database::createCollection` has the following
+
+   :phpmethod:`MongoDB\\Database::createCollection()` has the following
    parameters:
-   
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-createCollection-param.rst
-   
-   The ``$options`` parameter accepts the following options:
-   
+
+   The ``$options`` parameter supports the following options:
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-createCollection-option.rst
-   
-   Note that not all options are available on all versions of MongoDB.
-   Document Validation, for example, was added in MongoDB 3.2;
-   similarly, the WiredTiger storage engine is available only for
-   MongoDB 3.0 and later. Refer to the :manual:`create command
-   </reference/command/create>` reference in the MongoDB manual for
-   compatibility considerations.
 
-Output
-------
+   Note that not all options are available on all versions of MongoDB. Document
+   validation, for example, was added in MongoDB 3.2; similarly, the WiredTiger
+   storage engine is available only for MongoDB 3.0 and later. Refer to the
+   :manual:`create </reference/command/create>` command reference in the MongoDB
+   manual for compatibility considerations.
+
+   :returns:
 
-Returns the command result document as an array.
+      An array or object with the result document of the :manual:`create
+      </reference/command/create>` command.
 
 Example
 -------
@@ -61,6 +61,8 @@ database with document validation criteria:
 
 .. code-block:: php
 
+   <?php
+
    $db = (new MongoDB\Client)->demo;
 
    $result = $db->createCollection('users', [
@@ -69,13 +71,12 @@ database with document validation criteria:
            'email' => ['$regex' => '@mongodb\.com$'],
        ],
    ]);
-   
-   
+
    var_dump($result);
 
 The output would then resemble::
 
-   Object(MongoDB\Model\BSONDocument)#11 (1) {
+   object(MongoDB\Model\BSONDocument)#11 (1) {
      ["storage":"ArrayObject":private]=>
      array(1) {
        ["ok"]=>
@@ -85,5 +86,6 @@ The output would then resemble::
 
 .. seealso::
 
-   :manual:`create </reference/command/create>` command reference in
-   the MongoDB manual
+   - :manual:`create </reference/command/create>` command reference in the MongoDB
+     manual
+   - :manual:`db.createCollection() </reference/method/db.createCollection/>`

docs/reference/method/MongoDBDatabase-drop.txt

@@ -13,27 +13,27 @@ MongoDB\\Database::drop()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::drop
+.. phpmethod:: MongoDB\\Database::drop()
+
+   Drop the database.
 
-   Drops the database.
-   
    .. code-block:: php
-   
-      function dropCollection($collectionName, array $options = []): array|object
-   
-   :phpmethod:`MongoDB\\Database::drop` has the following
-   parameters:
-   
+
+      function drop(array $options = []): array|object
+
+   :phpmethod:`MongoDB\\Database::drop()` has the following parameters:
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-drop-param.rst
-   
-   The ``$options`` parameter accepts the following options:
-   
+
+   The ``$options`` parameter supports the following options:
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-drop-option.rst
 
-Output
-------
+   :returns:
 
-Returns the command result document as an array.
+      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
 -------
@@ -42,11 +42,12 @@ The following example drops the ``demo`` database:
 
 .. code-block:: php
 
+   <?php
+
    $db = (new MongoDB\Client)->demo;
 
    $result = $db->drop();
-   
-   
+
    var_dump($result);
 
 The output would then resemble::
@@ -63,6 +64,6 @@ The output would then resemble::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Client::dropDatabase`
-   - :manual:`dropDatabase </reference/command/dropDatabase>` command
-     reference in the MongoDB manual
+   - :phpmethod:`MongoDB\\Client::dropDatabase()`
+   - :manual:`dropDatabase </reference/command/dropDatabase>` command reference
+     in the MongoDB manual

docs/reference/method/MongoDBDatabase-dropCollection.txt

@@ -13,41 +13,42 @@ MongoDB\\Database::dropCollection()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::dropCollection
+.. phpmethod:: MongoDB\\Database::dropCollection()
 
    Drop a collection within the current database.
-   
+
    .. code-block:: php
-   
+
       function dropCollection($collectionName, array $options = []): array|object
-   
-   :phpmethod:`MongoDB\\Database::dropCollection` has the following
+
+   :phpmethod:`MongoDB\\Database::dropCollection()` has the following
    parameters:
-   
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-dropCollection-param.rst
-   
-   The ``$options`` parameter accepts the following options:
-   
+
+   The ``$options`` parameter supports the following options:
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-dropCollection-option.rst
 
-Output
-------
+   :returns:
 
-Returns the command result document as an array.
+      An array or object with the result document of the :manual:`drop
+      </reference/command/drop>` command. The return type will depend on
+      the ``typeMap`` option.
 
 Example
 -------
 
-The following example drops the ``users`` collection in the ``demo``
-database:
+The following example drops the ``users`` collection in the ``demo`` database:
 
 .. code-block:: php
 
+   <?php
+
    $db = (new MongoDB\Client)->demo;
 
    $result = $db->dropCollection('users');
-   
-   
+
    var_dump($result);
 
 The output would then resemble::
@@ -66,6 +67,6 @@ The output would then resemble::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::drop`
-   - :manual:`drop </reference/command/drop>` command reference in
-     the MongoDB manual
+   - :phpmethod:`MongoDB\\Collection::drop()`
+   - :manual:`drop </reference/command/drop>` command reference in the MongoDB
+     manual

docs/reference/method/MongoDBDatabase-getDatabaseName.txt

@@ -13,27 +13,27 @@ MongoDB\\Database::getDatabaseName()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::getDatabaseName
+.. phpmethod:: MongoDB\\Database::getDatabaseName()
+
+   Returns the name of this database.
 
-   Drops the database.
-   
    .. code-block:: php
-   
+
       function getDatabaseName(): string
 
-Output
-------
+   :returns:
 
-Returns the name of the database as a string.
+      The name of this database as a string.
 
 Example
 -------
 
-The following example gets the name of the database from the ``$db``
-variable:
+The following example prints the name of a database object:
 
 .. code-block:: php
 
+   <?php
+
    $db = (new MongoDB\Client)->demo;
 
    echo $db->getDatabaseName();

docs/reference/method/MongoDBDatabase-getManager.txt

@@ -17,7 +17,7 @@ Definition
 
    Accessor for the
    :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>` used by this
-   :phpclass:`Client <MongoDB\\Database>`.
+   :phpclass:`Database <MongoDB\\Database>`.
 
    .. code-block:: php
 

docs/reference/method/MongoDBDatabase-listCollections.txt

@@ -13,39 +13,38 @@ MongoDB\\Database::listCollections()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::listCollections
+.. phpmethod:: MongoDB\\Database::listCollections()
 
    Returns information for all collections in this database.
 
    .. code-block:: php
-   
-      function listCollections(array $options=[]): MongoDB\Model\CollectionInfoIterator
 
-   :phpmethod:`MongoDB\\Database::listCollections` has the following
+      function listCollections(array $options = []): MongoDB\Model\CollectionInfoIterator
+
+   :phpmethod:`MongoDB\\Database::listCollections()` has the following
    parameters:
-   
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-listCollections-param.rst
-   
-   The ``$options`` parameter accepts the following options:
-   
+
+   The ``$options`` parameter supports the following options:
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-listCollections-option.rst
 
-Output
-------
+   :returns:
 
-Returns information for all collections in the database. The elements
-in the returned iterator are ``MongoDB\Model\CollectionInfo`` objects.
+      A traversable :phpclass:`MongoDB\\Model\CollectionInfoIterator`, which
+      contains an :phpclass:`MongoDB\\Model\CollectionInfo` object for each
+      collection in the database.
 
 Example
 -------
 
-The following example lists all of the collections in the ``example``
-database:
+The following example lists all of the collections in the ``example`` database:
 
 .. code-block:: php
 
    <?php
-   
+
    $database = (new MongoDB\Client)->example;
 
    foreach ($database->listCollections() as $collectionInfo) {
@@ -61,7 +60,7 @@ The output would then resemble::
      array(0) {
      }
    }
-   object(MongoDB\Model\CollectionInfo)#11 (2) {
+   object(MongoDB\Model\CollectionInfo)#3 (2) {
      ["name"]=>
      string(5) "users"
      ["options"]=>
@@ -75,11 +74,47 @@ The output would then resemble::
      array(0) {
      }
    }
-   
+
+The following example lists all collections whose name starts with ``"rest"``
+in the ``example`` database:
+
+.. code-block:: php
+
+   <?php
+
+   $database = (new MongoDB\Client)->example;
+
+   $collections = $database->listCollections([
+       'filter' => [
+           'name' => new MongoDB\BSON\Regex('^rest.*'),
+       ],
+   ]);
+
+   foreach ($collections as $collectionInfo) {
+       var_dump($collectionInfo);
+   }
+
+The output would then resemble::
+
+   object(MongoDB\Model\CollectionInfo)#3 (2) {
+     ["name"]=>
+     string(11) "restaurants"
+     ["options"]=>
+     array(0) {
+     }
+   }
+   object(MongoDB\Model\CollectionInfo)#3 (2) {
+     ["name"]=>
+     string(6) "restos"
+     ["options"]=>
+     array(0) {
+     }
+   }
+
 .. seealso::
 
-   - :manual:`listCollections </reference/command/listCollections`
-     command reference in the MongoDB manual.
-   
-   - MongoDB Specification `Enumerating Collections 
-     <https://github.com/mongodb/specifications/blob/master/source/enumerate-collections.rst>`_
+   - :manual:`listCollections </reference/command/listCollections` command
+     reference in the MongoDB manual
+   - `Enumerating Collections
+     <https://github.com/mongodb/specifications/blob/master/source/enumerate-collections.rst>`_
+     specification
\ No newline at end of file

docs/reference/method/MongoDBDatabase-selectCollection.txt

@@ -13,128 +13,65 @@ MongoDB\\Database::selectCollection()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::selectCollection
+.. phpmethod:: MongoDB\\Database::selectCollection()
+
+   Selects a collection within the database.
 
-   Selects a collection within the database. The collection inherits
-   options such as read preference and type map from the Database object
-   unless otherwise specified in the ``$options`` parameter.
-   
    .. code-block:: php
-   
+
       function selectCollection($collectionName, array $options = []): MongoDB\Collection
-   
-   :phpmethod:`MongoDB\\Database::selectCollection` has the following
+
+   :phpmethod:`MongoDB\\Database::selectCollection()` has the following
    parameters:
-   
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-selectCollection-param.rst
-   
-   The ``$options`` parameter accepts the following options:
-   
+
+   The ``$options`` parameter supports the following options:
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-selectCollection-option.rst
 
-Output
-------
+   :returns:
+
+      A :phpclass:`MongoDB\\Collection` object.
+
+Behavior
+--------
 
-Returns a :phpclass:`MongoDB\\Collection` object.
+The selected collection inherits options such as read preference and type
+mapping from the :phpclass:`Database <MongoDB\\Database>` object. Options may be
+overridden via the ``$options`` parameter.
 
 Example
 -------
 
+The following example selects the ``users`` collection in the ``demo`` database:
+
+.. code-block:: php
+
+   <?php
+
+   $db = (new MongoDB\Client)->demo;
+
+   $collection = $db->selectCollection('demo', 'users');
+
 The following example selects the ``users`` collection in the ``demo``
 database with a custom read preference:
 
 .. code-block:: php
 
+   <?php
+
    $db = (new MongoDB\Client)->demo;
 
    $users = $db->selectCollection(
-      'users',
-      [ 
-         'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
-      ]
+       'users',
+       [
+           'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
+       ]
    );
-   
-   
-   var_dump($users);
-
-The output would then resemble::
-
-   object(MongoDB\Collection)#8 (7) {
-     ["collectionName"]=>
-     string(5) "users"
-     ["databaseName"]=>
-     string(4) "demo"
-     ["manager"]=>
-     object(MongoDB\Driver\Manager)#2 (2) {
-       ["uri"]=>
-       string(25) "mongodb://localhost:27017"
-       ["cluster"]=>
-       array(1) {
-         [0]=>
-         array(11) {
-           ["host"]=>
-           string(9) "localhost"
-           ["port"]=>
-           int(27017)
-           ["type"]=>
-           int(0)
-           ["is_primary"]=>
-           bool(false)
-           ["is_secondary"]=>
-           bool(false)
-           ["is_arbiter"]=>
-           bool(false)
-           ["is_hidden"]=>
-           bool(false)
-           ["is_passive"]=>
-           bool(false)
-           ["tags"]=>
-           array(0) {
-           }
-           ["last_is_master"]=>
-           array(0) {
-           }
-           ["round_trip_time"]=>
-           int(-1)
-         }
-       }
-     }
-     ["readConcern"]=>
-     object(MongoDB\Driver\ReadConcern)#5 (1) {
-       ["level"]=>
-       NULL
-     }
-     ["readPreference"]=>
-     object(MongoDB\Driver\ReadPreference)#3 (2) {
-       ["mode"]=>
-       int(2)
-       ["tags"]=>
-       array(0) {
-       }
-     }
-     ["typeMap"]=>
-     array(3) {
-       ["array"]=>
-       string(23) "MongoDB\Model\BSONArray"
-       ["document"]=>
-       string(26) "MongoDB\Model\BSONDocument"
-       ["root"]=>
-       string(26) "MongoDB\Model\BSONDocument"
-     }
-     ["writeConcern"]=>
-     object(MongoDB\Driver\WriteConcern)#7 (4) {
-       ["w"]=>
-       NULL
-       ["wmajority"]=>
-       bool(false)
-       ["wtimeout"]=>
-       int(0)
-       ["journal"]=>
-       NULL
-     }
-   }   
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::__construct`
-   - :phpmethod:`MongoDB\\Database::__get`
+   - :phpmethod:`MongoDB\\Database::__get()`
+   - :phpmethod:`MongoDB\\Client::selectCollection()`
+   - :phpmethod:`MongoDB\\Collection::__construct()`

docs/reference/method/MongoDBDatabase-withOptions.txt

@@ -4,45 +4,51 @@ MongoDB\\Database::withOptions()
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::withOptions
+.. phpmethod:: MongoDB\\Database::withOptions()
 
    Returns a clone of the Database object, but with different options.
-   
+
    .. code-block:: php
 
       function withOptions(array $options = []): MongoDB\Database
 
-   :phpmethod:`MongoDB\\Database::withOptions` supports the
-   following parameter:
-   
-   .. include:: /includes/apiargs/MongoDBCollection-method-withOptions-param.rst
-   
+   :phpmethod:`MongoDB\\Database::withOptions()` has the following parameters:
+
+   .. include:: /includes/apiargs/MongoDBDatabase-method-withOptions-param.rst
+
    The ``$options`` parameter supports the following options:
-   
-   .. include:: /includes/apiargs/MongoDBCollection-method-withOptions-option.rst
+
+   .. include:: /includes/apiargs/MongoDBDatabase-method-withOptions-option.rst
+
+   :returns:
+
+      A :phpclass:`MongoDB\\Database` object.
 
 Example
 -------
 
-The following example clones the ``$newDb`` Database object with read
-preference ``RP_SECONDARY``.
+The following example clones an existing Database object with a new read
+preference:
 
 .. code-block:: php
 
    <?php
-   
-   $database = new MongoDB\Client;
 
-   $newDb = $database->withOptions('sample','restaurants');
+   $db = (new MongoDB\Client)->demo;
 
-   $newCollection = $sourceCollection->withOptions([ 
+   $newDb = $db->withOptions([
        'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
    ]);
-   
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::__construct`
+   - :phpmethod:`MongoDB\\Database::__construct()`

docs/reference/method/MongoDBDatabase__construct.txt

@@ -13,7 +13,7 @@ MongoDB\\Database::__construct()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::__construct
+.. phpmethod:: MongoDB\\Database::__construct()
 
    Constructs a new :phpclass:`Database <MongoDB\\Database>` instance.
 
@@ -25,16 +25,20 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-construct-param.rst
 
-   :phpmethod:`MongoDB\\Database::__construct` supports the following
-   options:
-   
+   The ``$options`` parameter supports the following options:
+
    .. include:: /includes/apiargs/MongoDBDatabase-method-construct-option.rst
 
-   If you construct the Database explicitly, the Database inherits any
-   options from the ``Manager`` object. If you select the Database
-   from a :phpclass:`Client <MongoDB\\Client>` object, the Database
-   inherits its options from that object.
+Behavior
+--------
+
+If you construct a Database explicitly, the Database inherits any options from
+the :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>` object. If
+you select the Database from a :phpclass:`Client <MongoDB\\Client>` object, the
+Database inherits its options from that object.
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Database::withOptions`
+   - :phpmethod:`MongoDB\\Database::withOptions()`
+   - :phpmethod:`MongoDB\\Client::selectDatabase()`
+   - :phpmethod:`MongoDB\\Client::__get()`

docs/reference/method/MongoDBDatabase__get.txt

@@ -4,7 +4,6 @@ MongoDB\\Database::__get()
 
 .. default-domain:: mongodb
 
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -14,33 +13,37 @@ MongoDB\\Database::__get()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::__get($collectionName)
+.. phpmethod:: MongoDB\\Database::__get()
 
-   Select a collection from the database.
+   Select a collection within the database.
 
    .. code-block:: php
 
       function __get($collectionName): MongoDB\Collection
 
-   :phpmethod:`MongoDB\\Database::__get` has the following parameters:
+   :phpmethod:`MongoDB\\Database::__get()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-get-param.rst
 
+   :returns:
+
+      A :phpclass:`MongoDB\\Collection` object.
+
 Behavior
 --------
 
-The selected database inherits options such as read preference and
-type mapping from the :phpclass:`Database  <MongoDB\\Database>` object.
-If you wish to override any options, use the 
-:phpmethod:`MongoDB\\Database::selectCollection` method.
+The selected collection inherits options such as read preference and type
+mapping from the :phpclass:`Database <MongoDB\\Database>` object. If you wish to
+override any options, use the :phpmethod:`MongoDB\\Database::selectCollection`
+method.
 
 .. note::
-   
+
    To select collections whose names contain special characters, such as
    ``.``, use complex syntax, as in ``$database->{'that.database'}``.
-   
+
    Alternatively, :phpmethod:`MongoDB\\Database::selectCollection` supports
-   selecting databases whose names contain special characters.
+   selecting collections whose names contain special characters.
 
 Examples
 --------
@@ -59,5 +62,6 @@ collections from the ``demo`` database:
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Database::selectCollection`
-   - :php:`Property Overloading <oop5.overloading>` in the PHP Manual.
+   - :phpmethod:`MongoDB\\Database::selectCollection()`
+   - :phpmethod:`MongoDB\\Client::selectCollection()`
+   - :php:`Property Overloading <oop5.overloading>` in the PHP Manual