From 9eeba8cb28a270559fb35bffcb079dc95a761222 Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@php.net>
Date: Sun, 28 Dec 2014 22:05:21 +0000
Subject: [PATCH] Update docs for MongoCursor interator methods

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@335444 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../mongo/mongocommandcursor/current.xml      | 12 +++-
 reference/mongo/mongocommandcursor/key.xml    | 15 +++--
 reference/mongo/mongocommandcursor/next.xml   | 11 +++-
 reference/mongo/mongocommandcursor/rewind.xml | 57 +++++++++++++++----
 reference/mongo/mongocommandcursor/valid.xml  | 13 ++++-
 reference/mongo/mongocursor/current.xml       | 10 +++-
 reference/mongo/mongocursor/key.xml           | 15 ++++-
 reference/mongo/mongocursor/next.xml          |  7 +++
 reference/mongo/mongocursor/rewind.xml        |  7 +++
 reference/mongo/mongocursor/valid.xml         | 11 +++-
 10 files changed, 131 insertions(+), 27 deletions(-)

diff --git a/reference/mongo/mongocommandcursor/current.xml b/reference/mongo/mongocommandcursor/current.xml
index 6827012ce4..47a6d66e9c 100644
--- a/reference/mongo/mongocommandcursor/current.xml
+++ b/reference/mongo/mongocommandcursor/current.xml
@@ -14,7 +14,7 @@
    <void/>
   </methodsynopsis>
   <para>
-   This returns &null; until <function>MongoCommandCursor::next</function> is called.
+   This returns &null; until <function>MongoCommandCursor::rewind</function> is called.
   </para>
  </refsect1>
 
@@ -26,9 +26,17 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;  
   <para>
-   The current result as an associative array.
+   The current result document as an associative array. &null; will be returned
+   if there is no result.
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Iterator::current</methodname></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocommandcursor/key.xml b/reference/mongo/mongocommandcursor/key.xml
index 2507b0751e..79df013cce 100644
--- a/reference/mongo/mongocommandcursor/key.xml
+++ b/reference/mongo/mongocommandcursor/key.xml
@@ -4,13 +4,13 @@
 <refentry xml:id="mongocommandcursor.key" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>MongoCommandCursor::key</refname>
-  <refpurpose>Returns the current result&apos;s _id</refpurpose>
+  <refpurpose>Returns the current result&apos;s index within the result set</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>string</type><methodname>MongoCommandCursor::key</methodname>
+   <modifier>public</modifier> <type>int</type><methodname>MongoCommandCursor::key</methodname>
    <void/>
   </methodsynopsis>
  </refsect1>
@@ -21,11 +21,18 @@
  </refsect1>
 
  <refsect1 role="returnvalues">
-  &reftitle.returnvalues;  
+  &reftitle.returnvalues;
   <para>
-   The current result&apos;s _id as a string.
+   The current result&apos;s index within the result set.
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Iterator::key</methodname></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocommandcursor/next.xml b/reference/mongo/mongocommandcursor/next.xml
index 8a24284948..cd94fad9c4 100644
--- a/reference/mongo/mongocommandcursor/next.xml
+++ b/reference/mongo/mongocommandcursor/next.xml
@@ -21,7 +21,7 @@
  </refsect1>
 
  <refsect1 role="returnvalues">
-  &reftitle.returnvalues;  
+  &reftitle.returnvalues;
   <para>
    &null;.
   </para>
@@ -31,10 +31,17 @@
   &reftitle.errors;
   <para>
    Throws <classname>MongoConnectionException</classname> if it cannot reach the
-   database and <classname>MongoCommandCursorTimeoutException</classname> if the
+   database and <classname>MongoCursorTimeoutException</classname> if the
    timeout is exceeded.
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Iterator::next</methodname></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocommandcursor/rewind.xml b/reference/mongo/mongocommandcursor/rewind.xml
index 346b550a60..b50aab8fd4 100644
--- a/reference/mongo/mongocommandcursor/rewind.xml
+++ b/reference/mongo/mongocommandcursor/rewind.xml
@@ -13,6 +13,9 @@
    <modifier>public</modifier> <type>array</type><methodname>MongoCommandCursor::rewind</methodname>
    <void/>
   </methodsynopsis>
+  <para>
+   If the cursor has already started iteration, the command will be re-executed.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -21,11 +24,45 @@
  </refsect1>
 
  <refsect1 role="returnvalues">
-  &reftitle.returnvalues;  
+  &reftitle.returnvalues;
   <para>
    The raw server result document.
   </para>
-  <screen>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws <classname>MongoConnectionException</classname> if it cannot reach the
+   database and <classname>MongoCursorTimeoutException</classname> if the
+   timeout is exceeded.
+  </para>
+  <para>
+   Throws <classname>MongoCursorException</classname> if the cursor was created
+   with <function>MongoCommandCursor::createFromDocument</function> and has
+   already started iteration. Such cursors cannot be iterated multiple times, as
+   they lack the original command necessary for re-execution.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoCommandCursor::rewind</function></title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$rawResult = $commandCursor->rewind();
+
+// Command cursor is now reset to the start of the result set
+
+var_dump($rawResult);
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
 array(2) {
   ["cursor"]=>
   array(3) {
@@ -53,16 +90,16 @@ array(2) {
   ["ok"]=>
   float(1)
 }
-  </screen>
+]]>
+   </screen>
+  </example>
  </refsect1>
 
- <refsect1 role="errors">
-  &reftitle.errors;
-  <para>
-   Throws <classname>MongoConnectionException</classname> if it cannot reach the
-   database and <classname>MongoCommandCursorTimeoutException</classname> if the
-   timeout is exceeded.
-  </para>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Iterator::rewind</methodname></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/mongo/mongocommandcursor/valid.xml b/reference/mongo/mongocommandcursor/valid.xml
index 5e500e553f..c0f9944704 100644
--- a/reference/mongo/mongocommandcursor/valid.xml
+++ b/reference/mongo/mongocommandcursor/valid.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="mongocommandcursor.valid" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>MongoCommandCursor::valid</refname>
-  <refpurpose>Fetches a new result item, and returns whether it could</refpurpose>
+  <refpurpose>Checks if the cursor is reading a valid result.</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -21,11 +21,18 @@
  </refsect1>
 
  <refsect1 role="returnvalues">
-  &reftitle.returnvalues;  
+  &reftitle.returnvalues;
   <para>
-   &true; if a next item could be returned, and &false; otherwise.
+   &true; if the current result is not null, and &false; otherwise.
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Iterator::valid</methodname></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocursor/current.xml b/reference/mongo/mongocursor/current.xml
index d163e89b03..940f29d574 100644
--- a/reference/mongo/mongocursor/current.xml
+++ b/reference/mongo/mongocursor/current.xml
@@ -26,9 +26,17 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;  
   <para>
-   The current result as an associative array.
+   The current result document as an associative array. &null; will be returned
+   if there is no result.
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Iterator::current</methodname></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocursor/key.xml b/reference/mongo/mongocursor/key.xml
index cddda30114..8ad7f37dd1 100644
--- a/reference/mongo/mongocursor/key.xml
+++ b/reference/mongo/mongocursor/key.xml
@@ -4,13 +4,13 @@
 <refentry xml:id="mongocursor.key" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>MongoCursor::key</refname>
-  <refpurpose>Returns the current result&apos;s _id</refpurpose>
+  <refpurpose>Returns the current result&apos;s _id, or its index within the result set</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>string</type><methodname>MongoCursor::key</methodname>
+   <modifier>public</modifier> <type>string|int</type><methodname>MongoCursor::key</methodname>
    <void/>
   </methodsynopsis>
  </refsect1>
@@ -23,9 +23,18 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;  
   <para>
-   The current result&apos;s _id as a string.
+   The current result&apos;s <literal>_id</literal> as a string. If the result
+   has no <literal>_id</literal>, its numeric index within the result set will
+   be returned as an integer.
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Iterator::key</methodname></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocursor/next.xml b/reference/mongo/mongocursor/next.xml
index 23b0e39bbe..8b9fb049e1 100644
--- a/reference/mongo/mongocursor/next.xml
+++ b/reference/mongo/mongocursor/next.xml
@@ -35,6 +35,13 @@
    timeout is exceeded.
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Iterator::next</methodname></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocursor/rewind.xml b/reference/mongo/mongocursor/rewind.xml
index 011e3e0cb0..3cc6e56aea 100644
--- a/reference/mongo/mongocursor/rewind.xml
+++ b/reference/mongo/mongocursor/rewind.xml
@@ -50,6 +50,13 @@ public function rewind() {
    timeout is exceeded.
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Iterator::rewind</methodname></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocursor/valid.xml b/reference/mongo/mongocursor/valid.xml
index 4cd2181273..cc6168a8d8 100644
--- a/reference/mongo/mongocursor/valid.xml
+++ b/reference/mongo/mongocursor/valid.xml
@@ -21,11 +21,18 @@
  </refsect1>
 
  <refsect1 role="returnvalues">
-  &reftitle.returnvalues;  
+  &reftitle.returnvalues;
   <para>
-   If the current result is not null.
+   &true; if the current result is not null, and &false; otherwise.
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Iterator::valid</methodname></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables: