PHPLIB-1055: Various small documentation fixes (#1024)

* Use literals instead of RC/RP/WC constants for conciseness

* PHPLIB-1057: Note that geoHaystack was removed in MongoDB 5.0+

* Use correct boolean type in updateMany() example code

* Better clarify Database::command() purpose and examples

Also fixes two long-standing syntax errors in the example code

* Revise command tutorial and sync with command() docs

Remove the geoNear example since the command itself was removed in MongoDB 4.2.

Author: jmikola

docs/reference/method/MongoDBClient-selectCollection.txt

@@ -72,7 +72,7 @@ with a custom read preference:
        'test',
        'users',
        [
-           'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
+           'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'),
        ]
    );
 

docs/reference/method/MongoDBClient-selectDatabase.txt

@@ -71,7 +71,7 @@ preference:
    $db = $client->selectDatabase(
        'test',
        [
-           'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
+           'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'),
        ]
    );
 

docs/reference/method/MongoDBCollection-getReadConcern.txt

@@ -36,7 +36,7 @@ Example
    <?php
 
    $collection = (new MongoDB\Client)->selectCollection('test', 'users', [
-      'readConcern' => new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY),
+      'readConcern' => new MongoDB\Driver\ReadConcern('majority'),
    ]);
 
    var_dump($collection->getReadConcern());

docs/reference/method/MongoDBCollection-updateMany.txt

@@ -61,7 +61,7 @@ The following example updates all of the documents with the ``borough`` of
 
    $updateResult = $collection->updateMany(
        [ 'borough' => 'Queens' ],
-       [ '$set' => [ 'active' => 'True' ]]
+       [ '$set' => [ 'active' => true ]]
    );
 
    printf("Matched %d document(s)\n", $updateResult->getMatchedCount());

docs/reference/method/MongoDBCollection-withOptions.txt

@@ -52,7 +52,7 @@ preference:
    $collection = (new MongoDB\Client)->selectCollection('test', 'restaurants');
 
    $newCollection = $sourceCollection->withOptions([
-       'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
+       'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'),
    ]);
 
 See Also

docs/reference/method/MongoDBDatabase-command.txt

@@ -15,7 +15,9 @@ Definition
 
 .. phpmethod:: MongoDB\\Database::command()
 
-   Execute a :manual:`command </reference/command>` on the database.
+   Execute a :manual:`command </reference/command>` on the database. This is
+   generally used to execute commands that do not have a corresponding helper
+   method within the library.
 
    .. code-block:: php
 
@@ -43,9 +45,10 @@ Errors/Exceptions
 Example
 -------
 
-The following example executes a :manual:`ping
-</reference/command/ping>` command, which returns a cursor with a single
-result document:
+Most database commands return a single result document, which can be obtained by
+converting the returned cursor to an array and accessing its first element. The
+following example executes a :manual:`ping </reference/command/ping>` command
+and prints its result document:
 
 .. code-block:: php
 
@@ -55,7 +58,7 @@ result document:
 
    $cursor = $database->command(['ping' => 1]);
 
-   var_dump($c->toArray()[0]);
+   var_dump($cursor->toArray()[0]);
 
 The output would resemble:
 
@@ -69,9 +72,11 @@ The output would resemble:
      }
    }
 
-The following example executes a :manual:`listCollections
-</reference/command/listCollections>` command, which returns a cursor with
-multiple result documents:
+Some database commands return a cursor with multiple results. The following
+example executes :manual:`listCollections </reference/command/listCollections>`,
+which returns a cursor containing a result document for each collection in the
+``test`` database. Note that this example is illustrative; applications would
+generally use :phpmethod:`MongoDB\\Database::listCollections()` in practice.
 
 .. code-block:: php
 
@@ -81,7 +86,7 @@ multiple result documents:
 
    $cursor = $database->command(['listCollections' => 1]);
 
-   var_dump($c->toArray());
+   var_dump($cursor->toArray());
 
 The output would resemble:
 

docs/reference/method/MongoDBDatabase-getReadConcern.txt

@@ -36,7 +36,7 @@ Example
    <?php
 
    $database = (new MongoDB\Client)->selectDatabase('test', [
-      'readConcern' => new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY),
+      'readConcern' => new MongoDB\Driver\ReadConcern('majority'),
    ]);
 
    var_dump($database->getReadConcern());

docs/reference/method/MongoDBDatabase-selectCollection.txt

@@ -71,7 +71,7 @@ database with a custom read preference:
    $users = $db->selectCollection(
        'users',
        [
-           'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
+           'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'),
        ]
    );
 

docs/reference/method/MongoDBDatabase-selectGridFSBucket.txt

@@ -71,7 +71,7 @@ database with a custom read preference:
 
    $imagesBucket = $db->selectGridFSBucket([
        'bucketName' => 'images',
-       'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
+       'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'),
    ]);
 
 See Also

docs/reference/method/MongoDBDatabase-withOptions.txt

@@ -52,7 +52,7 @@ preference:
    $db = (new MongoDB\Client)->test;
 
    $newDb = $db->withOptions([
-       'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
+       'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'),
    ]);
 
 See Also

docs/reference/method/MongoDBGridFSBucket-getReadConcern.txt

@@ -37,7 +37,7 @@ Example
 
    $database = (new MongoDB\Client)->selectDatabase('test');
    $bucket = $database->selectGridFSBucket([
-      'readConcern' => new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY),
+      'readConcern' => new MongoDB\Driver\ReadConcern('majority'),
    ]);
 
    var_dump($bucket->getReadConcern());

docs/reference/method/MongoDBModelIndexInfo-isGeoHaystack.txt

@@ -17,13 +17,17 @@ Definition
 
 .. phpmethod:: MongoDB\\Model\\IndexInfo::isGeoHaystack()
 
-   Return whether the index is a :manual:`geoHaystack
-   </core/geohaystack>` index.
+   Return whether the index is a :manual:`geoHaystack </core/geohaystack>`
+   index.
 
    .. code-block:: php
 
       function isGeoHaystack(): boolean
 
+   .. note::
+
+      MongoDB 5.0 and later no longer supports geoHaystack indexes.
+
 Return Values
 -------------