From 63b0d9a05f6d54d9e5c0463f15094f05ecdd5982 Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@php.net>
Date: Sun, 28 Dec 2014 21:56:56 +0000
Subject: [PATCH] Revise docs and examples for creating MongoCommandCursors

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@335442 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../mongo/mongocommandcursor/construct.xml    | 38 +++++++++----------
 .../mongocommandcursor/createfromdocument.xml | 22 ++++++-----
 2 files changed, 31 insertions(+), 29 deletions(-)

diff --git a/reference/mongo/mongocommandcursor/construct.xml b/reference/mongo/mongocommandcursor/construct.xml
index 09127f0fae..93a13cd8eb 100644
--- a/reference/mongo/mongocommandcursor/construct.xml
+++ b/reference/mongo/mongocommandcursor/construct.xml
@@ -13,18 +13,17 @@
    <modifier>public</modifier> <methodname>MongoCommandCursor::__construct</methodname>
    <methodparam><type>MongoClient</type><parameter>connection</parameter></methodparam>
    <methodparam><type>string</type><parameter>ns</parameter></methodparam>
-   <methodparam choice="opt"><type>array</type><parameter>command</parameter><initializer>array()</initializer></methodparam>
+   <methodparam><type>array</type><parameter>command</parameter><initializer>array()</initializer></methodparam>
   </methodsynopsis>
   <para>
-   In many instances, you do not have to create a
-   <classname>MongoCommandCursor</classname> manually, but instead one of the
-   helper functions such as
-   <methodname>MongoCollection::aggregateCursor</methodname> and
-   <methodname>MongoCollection::parallelCollectionScan</methodname>. However,
-   if the server adds new commands that can return cursors, then manually
-   creating <classname>MongoCommandCursor</classname> objects is required.
-   However, it might be easier to use the
-   <methodname>MongoCommandCursor::createFromDocument</methodname> instead.
+   Generally, you should not have to construct a
+   <classname>MongoCommandCursor</classname> manually, as there are helper
+   functions such as <methodname>MongoCollection::aggregateCursor</methodname>
+   and <methodname>MongoCollection::parallelCollectionScan</methodname>;
+   however, if the server introduces new commands that can return cursors, this
+   constructor will be useful in the absence of specific helper methods. You may
+   also consider using
+   <methodname>MongoCommandCursor::createFromDocument</methodname>.
   </para>
  </refsect1>
 
@@ -41,17 +40,18 @@
        Database connection.
       </para>
      </listitem>
-    </varlistentry>   
+    </varlistentry>
     <varlistentry>
      <term>
       <parameter>ns</parameter>
      </term>
      <listitem>
       <para>
-       Full name of database and collection.
+       Full name of the database and collection (e.g.
+       <literal>"test.foo"</literal>)
       </para>
      </listitem>
-    </varlistentry>   
+    </varlistentry>
     <varlistentry>
      <term>
       <parameter>command</parameter>
@@ -61,7 +61,7 @@
        Database command.
       </para>
      </listitem>
-    </varlistentry>   
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -81,9 +81,8 @@
 <![CDATA[
 <?php
 $m = new MongoClient;
-$d = $m->demo;
 
-// setup the pipeline
+// Define the aggregation pipeline
 $pipeline = [
     [ '$group' => [
         '_id' => '$country_code',
@@ -92,17 +91,18 @@ $pipeline = [
     [ '$sort' => [ '_id' => 1 ] ],
 ];
 
-// run the command, and return a MongoCommandCursor object
-$r = $d->commandCursor(
+// Construct a MongoCommandCursor object
+$cursor = new MongoCommandCursor(
     $m, // MongoClient object
     'demo.cities', // namespace
     [
         'aggregate' => 'cities',
         'pipeline' => $pipeline,
+        'cursor' => [ 'batchSize' => 0 ],
     ]
 );
 
-foreach($r as $document) {
+foreach($cursor as $result) {
    …
 }
 ?>
diff --git a/reference/mongo/mongocommandcursor/createfromdocument.xml b/reference/mongo/mongocommandcursor/createfromdocument.xml
index 267d1b13d7..70412c3c10 100644
--- a/reference/mongo/mongocommandcursor/createfromdocument.xml
+++ b/reference/mongo/mongocommandcursor/createfromdocument.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="mongocommandcursor.createfromdocument" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>MongoCommandCursor::createFromDocument</refname>
-  <refpurpose>Create a new command cursor from an existing cursor document</refpurpose>
+  <refpurpose>Create a new command cursor from an existing command response document</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -17,7 +17,8 @@
   </methodsynopsis>
   <para>
    Use this method if you have a raw command result with cursor information in
-   it.
+   it. Note that cursors created with this method cannot be iterated multiple
+   times, as they will lack the original command necessary for re-execution.
   </para>
  </refsect1>
 
@@ -34,7 +35,7 @@
        Database connection.
       </para>
      </listitem>
-    </varlistentry>   
+    </varlistentry>
     <varlistentry>
      <term>
       <parameter>hash</parameter>
@@ -45,7 +46,7 @@
        to <methodname>MongoDB:command</methodname>.
       </para>
      </listitem>
-    </varlistentry>   
+    </varlistentry>
     <varlistentry>
      <term>
       <parameter>document</parameter>
@@ -56,11 +57,11 @@
        the <literal>id</literal>, <literal>ns</literal> and
        <literal>firstBatch</literal> fields. Such a document is obtained by
        calling the <methodname>MongoDB:command</methodname> with appropriate
-       arguments to return a cursor, and not just a result. See the example
-       below.
+       arguments to return a cursor, and not just an inline result. See the
+       example below.
       </para>
      </listitem>
-    </varlistentry>   
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -82,7 +83,7 @@
 $m = new MongoClient;
 $d = $m->demo;
 
-// setup the pipeline
+// Define the aggregation pipeline
 $pipeline = [
     [ '$group' => [
         '_id' => '$country_code',
@@ -91,7 +92,8 @@ $pipeline = [
     [ '$sort' => [ '_id' => 1 ] ],
 ];
 
-// run the command. The "cursor" option below instructs the server to return a cursor information document instead of results
+// Execute the command. The "cursor" option instructs the server to return
+// cursor information in the response instead of inline results.
 $r = $d->command(
     [
         'aggregate' => 'cities',
@@ -105,7 +107,7 @@ $r = $d->command(
 // Show result and hash
 var_dump( $r, $hash );
 
-// construct the command cursor
+// Construct the command cursor
 $cursor = MongoCommandCursor::createFromDocument( $m, $hash, $r );
 ?>
 ]]>