Merge pull request #144

Author: jmikola

docs/classes/client.md

@@ -1,86 +1,149 @@
 # MongoDB\Client
 
-`MongoDB\Client` serves as an entry point for the library and driver. It is
-constructed with the same arguments as the driver's `MongoDB\Driver\Manager`
-class, which it composes. Additional reference may be found in the
-[`MongoDB\Driver\Manager::__construct`](http://php.net/manual/en/mongodb-driver-manager.construct.php])
-and
-[Connection String](https://docs.mongodb.org/manual/reference/connection-string/)
-documentation.
+The MongoDB\Client class serves as an entry point for the library. It is the
+preferred class for connecting to a MongoDB server or cluster of servers and
+serves as a gateway for accessing individual databases and collections. It is
+analogous to the driver's [MongoDB\Driver\Manager][manager] class, which it
+composes.
 
+[manager]: http://php.net/mongodb-driver-manager
+
+---
+
+## __construct()
+
+```php
+function __construct($uri = 'mongodb://localhost:27017', array $uriOptions = [], array $driverOptions = [])
 ```
-/* By default, the driver connects to mongodb://localhost:27017 */
-$client = new MongoDB\Client;
 
-/* Any URI options will be merged into the URI string */
+Constructs a new Client instance.
+
+Additional URI options may be provided as the second argument and will take
+precedence over any like options present in the URI string (e.g. authentication
+credentials, query string parameters).
+
+Driver options may be provided as the third argument. In addition to any options
+supported by the extension, this library allows you to specify a default
+type map to apply to the cursors it creates. A more thorough description of type
+maps may be found in the driver's [Persistence documentation][typemap].
+
+[typemap]: http://php.net/manual/en/mongodb.persistence.php#mongodb.persistence.typemaps
+
+### Supported URI Options
+
+See [MongoDB\Driver\Manager::__construct()][manager-construct] and the
+[MongoDB manual][connection-string].
+
+[manager-construct]: http://php.net/manual/en/mongodb-driver-manager.construct.php
+[connection-string]: https://docs.mongodb.org/manual/reference/connection-string/
+
+### Supported Driver Options
+
+typeMap (array)
+:   Default type map for cursors and BSON documents.
+
+### Example
+
+By default, the driver connects to a standalone server on localhost via port
+27017. The following example demonstrates how to connect to a replica set.
+Additionally, it demonstrates a replica set with a custom read preference:
+
+```
+<?php
+
 $client = new MongoDB\Client(
     'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet',
-    ['readPreference' => 'secondaryPreferred']
+    [
+        'readPreference' => 'secondaryPreferred'
+    ]
 );
 ```
 
-Driver options may be provided as the third argument. In addition to options
-supported by the extension, the PHP library allows you to specify a default
-type map to apply to the cursors it creates. A more thorough description of type
-maps may be found in the driver's
-[Persistence documentation](http://php.net/manual/en/mongodb.persistence.php#mongodb.persistence.typemaps).
+By default, the library will unserialize 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
+[mongo extension][ext-mongo]:
+
+[ext-mongo]: http://php.net/mongo
 
 ```
-/* This example instructs the library to unserialize root and embedded BSON
- * documents as PHP arrays, like the legacy driver (i.e. ext-mongo). */
-$client = new MongoDB\Client(null, [], [
-    'typeMap' => ['root' => 'array', 'document' => 'array'],
+<?php
+
+$client = new MongoDB\Client(
+    null,
+    [],
+    ['typeMap' => ['root' => 'array', 'document' => 'array', 'array' => 'array']]
 );
 ```
 
-By default, the library will unserialize BSON documents and arrays as
-`MongoDB\Model\BSONDocument` and `MongoDB\Model\BSONArray` objects,
-respectively. Each of these model classes extends PHP's
-[`ArrayObject`](http://php.net/arrayobject) class and implements the driver's
-[`MongoDB\BSON\Serializable`](http://php.net/mongodb-bson-serializable) and
-[`MongoDB\BSON\Unserializable`](http://php.net/mongodb-bson-unserializable)
-interfaces.
+### See Also
+
+ * [MongoDB\Driver\Manager::__construct()][manager-construct]
+ * [MongoDB Manual: Connection String][connection-string]
 
-## Selecting Databases and Collections
+---
 
-The Client class provides methods for creating Database or Collection instances
-(using its internal Manager instance). When selecting a Database or Collection,
-the child will inherit options (e.g. read preference, type map) from the Client.
-New options may also be provided to the `selectDatabase()` and
-`selectCollection()` methods.
+## __get()
 
+```php
+function __get($databaseName): MongoDB\Database
 ```
+
+Select a database.
+
+The Database will inherit options (e.g. read preference, type map) from the
+Client object. Use [selectDatabase()](#selectdatabase) to override any options.
+
+**Note:** databases whose names contain special characters (e.g. "-") may be
+selected with complex syntax (e.g. `$client->{"that-database"}`) or
+[selectDatabase()](#selectdatabase).
+
+### Example
+
+The following example selects the "demo" and "another-app" databases:
+
+```
+<?php
+
 $client = new MongoDB\Client;
 
-/* Select the "demo" database */
-$db = $client->selectDatabase('demo');
+$demo = $client->demo;
+$anotherApp = $client->{'another-app'};
+```
 
-/* Select the "demo.users" collection */
-$collection = $client->selectCollection('demo', 'users');
+### See Also
+
+ * [MongoDB\Client::selectDatabase()](#selectdatabase)
+ * [PHP Manual: Property Overloading](http://php.net/oop5.overloading#object.get)
+
+---
 
-/* selectDatabase() and selectCollection() also take an options array, which can
- * override any options inherited from the Client. */
-$db = $client->selectDatabase('demo', [
-    'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
-]);
+## dropDatabase
 
-/* The property accessor may also be used to select a database without
- * specifying additional options. PHP's complex syntax may be used for selecting
- * databases whose names contain special characters (e.g. "-"). */
-$db = $client->demo;
-$db = $client->{'another-app'};
+```php
+function dropDatabase($databaseName, array $options = []): array|object
 ```
 
-## Database Management
+Drop a database. Returns the command result document.
 
-The Client class has several methods for managing databases.
+### Supported Options
 
-### Dropping Databases
+typeMap (array)
+:   Type map for BSON deserialization. This will only be used for the returned
+    command result document.
+
+### Example
+
+The following example drops the "demo" database:
 
 ```
+<?php
+
 $client = new MongoDB\Client;
 
 $result = $client->dropDatabase('demo');
+
 var_dump($result);
 ```
 
@@ -98,12 +161,36 @@ object(MongoDB\Model\BSONDocument)#8 (1) {
 }
 ```
 
-### Enumerating Databases
+### See Also
+
+ * [MongoDB\Database::drop()](database.md#drop)
+ * [MongoDB Manual: dropDatabase command](http://docs.mongodb.org/manual/reference/command/dropDatabase/)
+
+---
+
+## listDatabases()
 
+```php
+function listDatabases(array $options = []): MongoDB\Model\DatabaseInfoIterator
 ```
+
+Returns information for all database on the server. Elements in the returned
+iterator will be MongoDB\Model\DatabaseInfo objects.
+
+### Supported Options
+
+maxTimeMS (integer)
+:   The maximum amount of time to allow the query to run.
+
+### Example
+
+The following example lists all databases on the server:
+
+```
+<?php
+
 $client = new MongoDB\Client;
 
-/* listDatabases() returns an iterator of MongoDB\Model\DatabaseInfo objects */
 foreach ($client->listDatabases() as $databaseInfo) {
     var_dump($databaseInfo);
 }
@@ -129,3 +216,139 @@ object(MongoDB\Model\DatabaseInfo)#7 (3) {
   bool(false)
 }
 ```
+
+### See Also
+
+ * [MongoDB Manual: listDatabases command](http://docs.mongodb.org/manual/reference/command/listDatabases/)
+
+---
+
+## selectCollection()
+
+```php
+function selectCollection($databaseName, $collectionName, array $options = []): MongoDB\Collection
+```
+
+Select a collection on the server.
+
+The Collection will inherit options (e.g. read preference, type map) from the
+Client object unless otherwise specified.
+
+### Supported Options
+
+readConcern (MongoDB\Driver\ReadConcern)
+:   The default read concern to use for collection operations. Defaults to the
+    Client's read concern.
+
+readPreference (MongoDB\Driver\ReadPreference)
+:   The default read preference to use for collection operations. Defaults to
+    the Client's read preference.
+
+typeMap (array)
+:   Default type map for cursors and BSON documents. Defaults to the Client's
+    type map.
+
+writeConcern (MongoDB\Driver\WriteConcern)
+:   The default write concern to use for collection operations. Defaults to the
+    Client's write concern.
+
+### Example
+
+The following example selects the "demo.users" collection:
+
+```
+<?php
+
+$client = new MongoDB\Client;
+
+$collection = $client->selectCollection('demo', 'users');
+```
+
+The following examples selects the "demo.users" collection with a custom read
+preference:
+
+```
+<?php
+
+$client = new MongoDB\Client;
+
+$collection = $client->selectCollection(
+    'demo',
+    'users',
+    [
+        'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
+    ]
+);
+```
+
+### See Also
+
+ * [MongoDB\Collection::__construct()](collection.md#__construct)
+ * [MongoDB\Client::__get()](#__get)
+
+
+---
+
+## selectDatabase()
+
+```php
+function selectDatabase($databaseName array $options = []): MongoDB\Collection
+```
+
+Select a database on the server.
+
+The Database will inherit options (e.g. read preference, type map) from the
+Client object unless otherwise specified.
+
+### Supported Options
+
+readConcern (MongoDB\Driver\ReadConcern)
+:   The default read concern to use for database operations. Defaults to the
+    Client's read concern.
+
+readPreference (MongoDB\Driver\ReadPreference)
+:   The default read preference to use for database operations. Defaults to the
+    Client's read preference.
+
+typeMap (array)
+:   Default type map for cursors and BSON documents. Defaults to the Client's
+    type map.
+
+writeConcern (MongoDB\Driver\WriteConcern)
+:   The default write concern to use for database operations. Defaults to the
+    Client's write concern.
+
+### Example
+
+The following example selects the "demo" database:
+
+```
+<?php
+
+$client = new MongoDB\Client;
+
+$db = $client->selectDatabase('demo');
+```
+
+The following examples selects the "demo" database with a custom read
+preference:
+
+```
+<?php
+
+$client = new MongoDB\Client;
+
+$db = $client->selectDatabase(
+    'demo',
+    [
+        'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
+    ]
+);
+```
+
+### See Also
+
+ * [MongoDB\Database::__construct()](database.md#__construct)
+ * [MongoDB\Client::__get()](#__get)
+
+---