PHPLIB-328: Document MapReduceResult class

docs/reference/method/MongoDBCollection-mapReduce.txt

@@ -36,7 +36,7 @@ Return Values
 -------------
 
 A :phpclass:`MongoDB\\MapReduceResult` object, which allows for iteration of
-mapReduce results irrespective of the output method (e.g. inline, collection)
+map-reduce results irrespective of the output method (e.g. inline, collection)
 via the :php:`IteratorAggregate <iteratoraggregate>` interface. It also
 provides access to command statistics.
 
@@ -117,7 +117,6 @@ The output would then resemble::
       float(3665228)
    }
 
-
 See Also
 --------
 

docs/reference/method/MongoDBMapReduceResult-getCounts.txt

+=====================================
+MongoDB\\MapReduceResult::getCounts()
+=====================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\MapReduceResult::getCounts()
+
+   Returns count statistics for the map-reduce operation.
+
+   .. code-block:: php
+
+      function getCounts(): array
+
+Return Values
+-------------
+
+An array of count statistics for the map-reduce operation.
+
+Examples
+--------
+
+This example reports the count statistics for a map-reduce operation.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->zips;
+
+   $map = new MongoDB\BSON\Javascript('function() { emit(this.state, this.pop); }');
+   $reduce = new MongoDB\BSON\Javascript('function(key, values) { return Array.sum(values) }');
+   $out = ['inline' => 1];
+
+   $result = $collection->mapReduce($map, $reduce, $out);
+
+   var_dump($result->getCounts());
+
+The output would then resemble::
+
+   array(4) {
+     ["input"]=>
+     int(29353)
+     ["emit"]=>
+     int(29353)
+     ["reduce"]=>
+     int(180)
+     ["output"]=>
+     int(51)
+   }
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\Collection::mapReduce()`
+- :manual:`mapReduce </reference/command/mapReduce>` command reference in the
+  MongoDB manual

docs/reference/method/MongoDBMapReduceResult-getExecutionTimeMS.txt

+==============================================
+MongoDB\\MapReduceResult::getExecutionTimeMS()
+==============================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\MapReduceResult::getExecutionTimeMS()
+
+   Returns the execution time in milliseconds of the map-reduce operation.
+
+   .. code-block:: php
+
+      function getExecutionTimeMS(): integer
+
+Return Values
+-------------
+
+An integer denoting the execution time in milliseconds for the map-reduce
+operation.
+
+Examples
+--------
+
+This example reports the execution time for a map-reduce operation.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->zips;
+
+   $map = new MongoDB\BSON\Javascript('function() { emit(this.state, this.pop); }');
+   $reduce = new MongoDB\BSON\Javascript('function(key, values) { return Array.sum(values) }');
+   $out = ['inline' => 1];
+
+   $result = $collection->mapReduce($map, $reduce, $out);
+
+   var_dump($result->getExecutionTimeMS());
+
+The output would then resemble::
+
+   int(244)
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\Collection::mapReduce()`
+- :manual:`mapReduce </reference/command/mapReduce>` command reference in the
+  MongoDB manual

docs/reference/method/MongoDBMapReduceResult-getIterator.txt

+=======================================
+MongoDB\\MapReduceResult::getIterator()
+=======================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\MapReduceResult::getIterator()
+
+   Returns a php:`Traversable <traversable>`, which may be used to iterate
+   through the results of the map-reduce operation.
+
+   .. code-block:: php
+
+      function getIterator(): Traversable
+
+Return Values
+-------------
+
+A :php:`Traversable <traversable>`, which may be used to iterate through the
+results of the map-reduce operation.
+
+Example
+-------
+
+This example iterates through the results of a map-reduce operation.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->zips;
+
+   $map = new MongoDB\BSON\Javascript('function() { emit(this.state, this.pop); }');
+   $reduce = new MongoDB\BSON\Javascript('function(key, values) { return Array.sum(values) }');
+   $out = ['inline' => 1];
+
+   $result = $collection->mapReduce($map, $reduce, $out);
+
+   foreach ($result as $population) {
+      var_dump($population);
+   };
+
+The output would then resemble::
+
+   object(stdClass)#2293 (2) {
+      ["_id"]=>
+      string(2) "AK"
+      ["value"]=>
+      float(544698)
+   }
+   object(stdClass)#2300 (2) {
+      ["_id"]=>
+      string(2) "AL"
+      ["value"]=>
+      float(4040587)
+   }
+   object(stdClass)#2293 (2) {
+      ["_id"]=>
+      string(2) "AR"
+      ["value"]=>
+      float(2350725)
+   }
+   object(stdClass)#2300 (2) {
+      ["_id"]=>
+      string(2) "AZ"
+      ["value"]=>
+      float(3665228)
+   }
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\Collection::mapReduce()`
+- :php:`IteratorAggregate::getIterator() <manual/en/iteratoraggregate.getiterator.php>`

docs/reference/method/MongoDBMapReduceResult-getTiming.txt

+=====================================
+MongoDB\\MapReduceResult::getTiming()
+=====================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\MapReduceResult::getTiming()
+
+   Returns timing statistics for the map-reduce operation.
+
+   .. code-block:: php
+
+      function getTiming(): array
+
+   Timing statistics will only be available if the ``verbose`` option was
+   specified for :phpmethod:`MongoDB\\Collection::mapReduce()`.
+
+Return Values
+-------------
+
+An array of timing statistics for the map-reduce operation. If no timing
+statistics are available, the array will be empty.
+
+Examples
+--------
+
+This example specifies the ``verbose`` option for
+:phpmethod:`MongoDB\\Collection::mapReduce()` and reports the timing statistics
+for a map-reduce operation.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->zips;
+
+   $map = new MongoDB\BSON\Javascript('function() { emit(this.state, this.pop); }');
+   $reduce = new MongoDB\BSON\Javascript('function(key, values) { return Array.sum(values) }');
+   $out = ['inline' => 1];
+
+   $result = $collection->mapReduce($map, $reduce, $out, ['verbose' => true]);
+
+   var_dump($result->getTiming());
+
+The output would then resemble::
+
+   array(5) {
+     ["mapTime"]=>
+     int(163)
+     ["emitLoop"]=>
+     int(233)
+     ["reduceTime"]=>
+     int(9)
+     ["mode"]=>
+     string(5) "mixed"
+     ["total"]=>
+     int(233)
+   }
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\Collection::mapReduce()`
+- :manual:`mapReduce </reference/command/mapReduce>` command reference in the
+  MongoDB manual

docs/reference/result-classes.txt

@@ -40,3 +40,34 @@ Methods
    /reference/method/MongoDBChangeStream-next
    /reference/method/MongoDBChangeStream-rewind
    /reference/method/MongoDBChangeStream-valid
+
+----
+
+MongoDB\\MapReduceResult
+------------------------
+
+.. versionadded:: 1.2
+
+Definition
+~~~~~~~~~~
+
+.. phpclass:: MongoDB\\MapReduceResult
+
+   This class extends PHP's :php:`IteratorAggregate <iteratoraggregate>`
+   interface. An instance of this class is returned by
+   :phpmethod:`MongoDB\\Collection::mapReduce()`.
+
+   This class allows for iteration of map-reduce results irrespective of the
+   output method (e.g. inline, collection). It also provides access to command
+   statistics.
+
+Methods
+~~~~~~~
+
+.. toctree::
+   :titlesonly:
+
+   /reference/method/MongoDBMapReduceResult-getCounts
+   /reference/method/MongoDBMapReduceResult-getExecutionTimeMS
+   /reference/method/MongoDBMapReduceResult-getIterator
+   /reference/method/MongoDBMapReduceResult-getTiming