Modified: phpdoc/en/trunk/reference/mongo/mongobindata.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongobindata.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongobindata.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -18,9 +18,12 @@
     The maximum size of a single object that can be inserted into the database
     is 4Mb.  For data that is larger than this (movies, music, Henry Kissinger's
     autobiography), use <classname>MongoGridFS</classname>. For data that is
-    smaller than 4Mb, it will probably be easier to just embed it into the
-    document using <classname>MongoBinData</classname>.
+    smaller than 4Mb, it's probably be easier to just embed it into the document
+    using <classname>MongoBinData</classname>.
    </para>
+   <para>
+    For example, to embed an image in a document, one could write:
+   </para>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -33,6 +36,13 @@
 ?>
 ]]>
    </programlisting>
+   <para>
+    This class contains a <varname>type</varname> field, which is currently
+    gives no additional functionality in the driver or the database.  There are
+    five predefined types (which are the class constants listed below), and the
+    user can create their own (at the risk of the BSON spec catching up with
+    them). By default, the PHP driver always uses type 2: a byte array.
+   </para>
   </section>
 <!-- }}} -->


Modified: phpdoc/en/trunk/reference/mongo/mongocode/construct.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocode/construct.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocode/construct.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -59,7 +59,12 @@
 <![CDATA[
 <?php

-$code = new MongoCode('function(x) { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } return x-1; }', array("x" => 4));
+$code = new MongoCode('function() { '.
+    'for(i=0;i<10;i++) {'.
+        'db.foo.update({z : i}, {z : x});'.
+    '}'.
+    'return x-1;'.
+ '}', array("x" => 4));
 var_dump($code);

 ?>
@@ -75,7 +80,7 @@
     int(4)
   }
   ["code"]=>
-  string(80) "function(x) { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } return x-1; }"
+  string(80) "function() { for(i=0;i<10;i++) { db.foo.update({z : i}, {z : x}); } return x-1; }"
 }
 ]]>
    </screen>

Modified: phpdoc/en/trunk/reference/mongo/mongocollection/construct.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocollection/construct.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocollection/construct.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -58,7 +58,7 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Throws InvalidArgumentException if the collection name is invalid.
+   Throws <classname>InvalidArgumentException</classname> if the collection name is invalid.
   </para>
  </refsect1>
 </refentry>

Modified: phpdoc/en/trunk/reference/mongo/mongocollection/count.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocollection/count.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocollection/count.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -11,8 +11,7 @@
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>int</type><methodname>MongoCollection::count</methodname>
-   <methodparam choice="opt"><type>array</type><parameter>query</parameter><initializer>array()</initializer></methodparam>
-   <methodparam choice="opt"><type>array</type><parameter>fields</parameter><initializer>array()</initializer></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>query</parameter><initializer>array()</initializer></methodparam>
   </methodsynopsis>
  </refsect1>

@@ -26,20 +25,10 @@
      </term>
      <listitem>
       <para>
-       Only count documents matching this query.
+       Array or object with fields to match.
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
-     <term>
-      <parameter>fields</parameter>
-     </term>
-     <listitem>
-      <para>
-       Only count documents with these fields.
-      </para>
-     </listitem>
-    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -47,7 +36,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns the number of documents.
+   Returns the number of documents matching the query.
   </para>
  </refsect1>


Modified: phpdoc/en/trunk/reference/mongo/mongocollection/findone.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocollection/findone.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocollection/findone.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -49,6 +49,13 @@
    Returns record matching the search or &null;.
   </para>
  </refsect1>
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws <classname>MongoConnectionException</classname> if it cannot reach the
+   database.
+  </para>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:

Modified: phpdoc/en/trunk/reference/mongo/mongocollection.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocollection.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocollection.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -15,8 +15,7 @@
     Representations a database collection.
    </para>
    <para>
-    Collection names cannot have a &quot;$&quot; in them, but other than that
-    they can use any character in the ASCII set.  Some valid collection
+    Collection names can use any character in the ASCII set.  Some valid collection
     names are &quot;&quot;, &quot;...&quot;, &quot;my collection&quot;, and &quot;&#42;&amp;&#35;&#64;&quot;.
    </para>
   </section>

Modified: phpdoc/en/trunk/reference/mongo/mongoconnectionexception.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongoconnectionexception.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongoconnectionexception.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -16,8 +16,8 @@
    </para>

    <para>
-    There are a number of possible error messages, to attempt
-    to help you diagnose the connection problem.  These are:
+    There are a number of possible error messages to help you diagnose the
+    connection problem.  These are:
    </para>

    <itemizedlist>

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/count.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/count.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/count.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -75,6 +75,13 @@
   </example>
  </refsect1>

+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws <classname>MongoConnectionException</classname> if it cannot reach the
+   database.
+  </para>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/current.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/current.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/current.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -4,7 +4,7 @@
 <refentry xml:id="mongocursor.current" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>MongoCursor::current</refname>
-  <refpurpose>Returns the current result</refpurpose>
+  <refpurpose>Returns the current element</refpurpose>
  </refnamediv>

  <refsect1 role="description">
@@ -13,6 +13,9 @@
    <modifier>public</modifier> <type>array</type><methodname>MongoCursor::current</methodname>
    <void/>
   </methodsynopsis>
+  <para>
+   This field is &null; until <function>MongoCursor::next</function> is called.
+  </para>
  </refsect1>

  <refsect1 role="parameters">
@@ -23,7 +26,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The current result.
+   The current result as an associative array.
   </para>
  </refsect1>
 </refentry>

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/dead.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/dead.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/dead.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -18,6 +18,13 @@
    per response. This method checks if the database has more batches or if the
    result set has been exhausted.
   </para>
+  <para>
+   A cursor being "dead" does not mean that
+   <function>MongoCursor::hasNext</function> will return &false;, it only means
+   that the database is done sending results to the client. The client should
+   continue iterating through results until
+   <function>MongoCursor::hasNext</function> is &false;.
+  </para>
  </refsect1>

  <refsect1 role="parameters">

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/doquery.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/doquery.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/doquery.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -26,6 +26,14 @@
    &null;.
   </para>
  </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws <classname>MongoConnectionException</classname> if it cannot reach the
+   database.
+  </para>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/explain.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/explain.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/explain.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -26,6 +26,87 @@
    Returns an explanation of the query.
   </para>
  </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoCursor::explain</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$cursor = $collection->find(array("x"=>1), array("y"))
+$cursor->sort(array("z" => 1))->limit(4)->skip(5);
+
+var_dump($cursor->explain());
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+array(8) {
+  ["cursor"]=>
+  string(15) "BtreeCursor x_1"
+  ["startKey"]=>
+  array(1) {
+    ["x"]=>
+    int(1)
+  }
+  ["endKey"]=>
+  array(1) {
+    ["x"]=>
+    int(1)
+  }
+  ["nscanned"]=>
+  float(4)
+  ["n"]=>
+  int(4)
+  ["scanAndOrder"]=>
+  int(1)
+  ["millis"]=>
+  int(3)
+  ["allPlans"]=>
+  array(2) {
+    [0]=>
+    array(3) {
+      ["cursor"]=>
+      string(15) "BtreeCursor x_1"
+      ["startKey"]=>
+      array(1) {
+        ["x"]=>
+        int(1)
+      }
+      ["endKey"]=>
+      array(1) {
+        ["x"]=>
+        int(1)
+      }
+    }
+    [1]=>
+    array(3) {
+      ["cursor"]=>
+      string(11) "BasicCursor"
+      ["startKey"]=>
+      array(0) {
+      }
+      ["endKey"]=>
+      array(0) {
+      }
+    }
+  }
+}
+]]>
+   </screen>
+  </example>
+ </refsect1>
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws <classname>MongoConnectionException</classname> if it cannot reach the
+   database.
+  </para>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/getnext.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/getnext.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/getnext.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -13,6 +13,10 @@
    <modifier>public</modifier> <type>array</type><methodname>MongoCursor::getNext</methodname>
    <void/>
   </methodsynopsis>
+  <para>
+   This equivalent to calling <function>MongoCursor::next</function>, then
+   <function>MongoCursor::current</function>.
+  </para>
  </refsect1>

  <refsect1 role="parameters">
@@ -26,6 +30,13 @@
    Returns the next object.
   </para>
  </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws <classname>MongoConnectionException</classname> if it cannot reach the database.
+  </para>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/hasnext.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/hasnext.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/hasnext.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -26,6 +26,13 @@
    Returns if there is another element.
   </para>
  </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws <classname>MongoConnectionException</classname> if it cannot reach the database.
+  </para>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/hint.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/hint.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/hint.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -43,7 +43,7 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Throws MongoCursorException if this cursor has started iterating.
+   Throws <classname>MongoCursorException</classname> if this cursor has started iterating.
   </para>
  </refsect1>
 </refentry>

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/key.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/key.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/key.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -23,7 +23,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The current result&apos;s _id.
+   The current result&apos;s _id as a string.
   </para>
  </refsect1>
 </refentry>

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/limit.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/limit.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/limit.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -43,7 +43,7 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Throws MongoCursorException if this cursor has started iterating.
+   Throws <classname>MongoCursorException</classname> if this cursor has started iterating.
   </para>
  </refsect1>


Modified: phpdoc/en/trunk/reference/mongo/mongocursor/next.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/next.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/next.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -26,6 +26,13 @@
    &null;.
   </para>
  </refsect1>
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws <classname>MongoConnectionException</classname> if it cannot reach the
+   database.
+  </para>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/skip.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/skip.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/skip.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -43,7 +43,7 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Throws MongoCursorException if this cursor has started iterating.
+   Throws <classname>MongoCursorException</classname> if this cursor has started iterating.
   </para>
  </refsect1>


Modified: phpdoc/en/trunk/reference/mongo/mongocursor/slaveokay.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/slaveokay.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/slaveokay.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -46,7 +46,7 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Throws MongoCursorException if this cursor has started iterating.
+   Throws <classname>MongoCursorException</classname> if this cursor has started iterating.
   </para>
  </refsect1>


Modified: phpdoc/en/trunk/reference/mongo/mongocursor/snapshot.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/snapshot.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/snapshot.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -42,7 +42,7 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Throws MongoCursorException if this cursor has started iterating.
+   Throws <classname>MongoCursorException</classname> if this cursor has started iterating.
   </para>
  </refsect1>
 </refentry>

Modified: phpdoc/en/trunk/reference/mongo/mongocursor/sort.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/sort.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/sort.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -43,7 +43,7 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Throws MongoCursorException if this cursor has started iterating.
+   Throws <classname>MongoCursorException</classname> if this cursor has started iterating.
   </para>
  </refsect1>


Modified: phpdoc/en/trunk/reference/mongo/mongocursor/tailable.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/tailable.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/tailable.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -52,7 +52,7 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Throws MongoCursorException if this cursor has started iterating.
+   Throws <classname>MongoCursorException</classname> if this cursor has started iterating.
   </para>
  </refsect1>


Modified: phpdoc/en/trunk/reference/mongo/mongocursor.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursor.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -28,7 +28,7 @@
     <function>MongoCursor::next</function>, directly or indirectly), the cursor
     moves into the post-query stage.  At this point, the query has been executed
     by the database and cannot be modified anymore.  At this point, the only
-    functions available are the iterator functions,
+    functions available are the <classname>Iterator</classname> functions,
     <function>MongoCursor::hasNext</function>, and
     <function>MongoCursor::getNext</function>.
    </para>

Modified: phpdoc/en/trunk/reference/mongo/mongocursorexception.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursorexception.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongocursorexception.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -59,16 +59,20 @@
       <literal>incomplete response</literal>
      </para>
      <para>
-      Occurs if the database response is malformed.
+      Occurs if the database response started out correctly, but broke off in
+      the middle.
      </para>
     </listitem>
     <listitem>
      <para>
-      <literal>[WSA ]error getting database response: errstr</literal>
+      <literal>error getting database response: errstr</literal>
      </para>
      <para>
+      <literal>WSA error getting database response: errstr</literal>
+     </para>
+     <para>
       "errstr" is an io error reported directly from the C socket
-      subsystem.  On Windows, is prefixed with "WSA".
+      subsystem.  On Windows, the error message is prefixed with "WSA".
      </para>
     </listitem>
    </itemizedlist>

Modified: phpdoc/en/trunk/reference/mongo/mongodbref/isref.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongodbref/isref.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongodbref/isref.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -11,8 +11,14 @@
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <modifier>static</modifier> <type>boolean</type><methodname>MongoDBRef::isRef</methodname>
-   <methodparam><type>array</type><parameter>ref</parameter></methodparam>
+   <methodparam><type>mixed</type><parameter>ref</parameter></methodparam>
   </methodsynopsis>
+  <para>
+   This not actually follow the reference, so it does not determine if it is
+   broken or not.  It merely checks that <parameter>ref</parameter> is in valid
+   database reference format (in that it is an object or array with $ref and $id
+   fields).
+  </para>
  </refsect1>

  <refsect1 role="parameters">
@@ -25,7 +31,7 @@
      </term>
      <listitem>
       <para>
-       Array to check.
+       Array or object to check.
       </para>
      </listitem>
     </varlistentry>
@@ -36,9 +42,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns if <literal>ref</literal> is a reference.  Does not actually follow
-   the reference, so it does not determine if it is broken or not.  It merely
-   checks that <parameter>ref</parameter> is valid database reference format.
+   Returns if <parameter>ref</parameter> is a reference.
   </para>
  </refsect1>
 </refentry>

Modified: phpdoc/en/trunk/reference/mongo/mongodbref.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongodbref.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongodbref.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -16,9 +16,11 @@
     different collections.
    </para>
    <para>
-    <emphasis>Motivation</emphasis>: Suppose we need to refer to point to a
-    document in another collection. The easiest way is to create a field in the
-    current document, something like:
+    <emphasis>Motivation</emphasis>: Suppose we need to refer to a document in
+    another collection. The easiest way is to create a field in the current
+    document.  For example, if we had a "people" collection and an "addresses"
+    collection, we might want to create a link between each person document and
+    and address document:
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -44,17 +46,30 @@
     </programlisting>
    </para>
    <para>
-    Suppose now that we have a more general case, where we don't know what
-    collection contains the referenced document.  MongoDBRef is a good choice
-    for this case, as it is a common format that all of the drivers and the
-    database understand.
+    Then, later on, we can find the person's address by querying the "addresses"
+    collection with the <classname>MongoId</classname> we saved in the "people"
+    collection.
+   </para>
+   <para>
+    Suppose now that we have a more general case, where we don't know which
+    collection (or even which database) contains the referenced document.
+    <classname>MongoDBRef</classname> is a good choice for this case, as it is a
+    common format that all of the drivers and the database understand.
+   </para>
+   <para>
+    If each person had a list of things they liked which could come from
+    multiple collections, such as "hobbies", "sports", "books", etc., we could
+    use <classname>MongoDBRef</classname>s to keep track of what "like" went
+    with what collection:
     <programlisting role="php">
 <![CDATA[
 <?php

 $people = $db->selectCollection("people");

+// model trains are in the "hobbies" collection
 $trainRef = MongoDBRef::create("hobbies", $modelTrains['_id']);
+// soccer is in the "sports" collection
 $soccerRef = MongoDBRef::create("sports", $soccer['_id']);

 // now we'll know what collections the items in the "likes" array came from when

Modified: phpdoc/en/trunk/reference/mongo/mongoid/construct.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongoid/construct.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongoid/construct.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -25,7 +25,9 @@
      </term>
      <listitem>
       <para>
-       A string to use as the id.
+       A string to use as the id.  Must be 24 hexidecimal characters. If an
+       invalid string is passed to this constructor, the constructor will ignore
+       it and create a new id value.
       </para>
      </listitem>
     </varlistentry>
@@ -44,7 +46,11 @@
   &reftitle.examples;
   <example>
    <title><function>MongoId::__construct</function> example</title>
-   <para>This example shows how to create a new id. This is seldom necessary, as the driver adds an id to arrays automatically before storing them in the database.</para>
+   <para>
+    This example shows how to create a new id. This is seldom necessary, as the
+    driver adds an id to arrays automatically before storing them in the
+    database.
+   </para>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -52,7 +58,7 @@
   $id1 = new MongoId();
   echo "$id1\n";

-  $id1 = new MongoId();
+  $id2 = new MongoId();
   echo "$id2\n";

   ?>
@@ -65,9 +71,6 @@
 49a702d5450046d3d515d10d
 ]]>
    </screen>
-   <para>
-    Note that the second hexadecimal number is greater than the first.
-   </para>
   </example>
   <example>
    <title>Parameter example</title>

Modified: phpdoc/en/trunk/reference/mongo/mongoid/tostring.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongoid/tostring.xml	2009-11-19 23:00:15 UTC (rev 291044)
+++ phpdoc/en/trunk/reference/mongo/mongoid/tostring.xml	2009-11-19 23:17:53 UTC (rev 291045)
@@ -34,13 +34,12 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-$obj = array( "x" => "y" );

 $m = new Mongo();
 $collection = $m->selectDB("foo")->selectCollection("bar");

-$collection->insert($obj);
-$collection->insert($obj);
+$collection->insert(array( "x" => "y" ));
+$collection->insert(array( "x" => "y" ));

 $cursor = $collection->find();
 $r1 = cursor->next();
@@ -48,6 +47,7 @@

 echo $r1["_id"] . "\n";
 echo $r2["_id"] . "\n";
+
 ?>
 ]]>
    </programlisting>