improved connection info

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@307768 c90b9560-bf6c-de11-be94-00142212c4b1

reference/mongo/mongo.xml

@@ -11,11 +11,10 @@
   <section xml:id="mongo.intro">
    &reftitle.intro;
    <para>
-    The connection point between MongoDB and PHP.
+    A connection between PHP and MongoDB.
    </para>
    <para>
-    This class is used to initiate a connection and for database server commands.
-    A typical use is:
+    This class is used to create and manage connections. A typical use is:
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -28,8 +27,9 @@ $db = $m->foo; // get the database named "foo"
     </programlisting>
    </para>
    <para>
-    See <function>Mongo::__construct</function> for more information about 
-    creating connections.
+    See <function>Mongo::__construct</function> and the section on
+    <link linkend="mongo.connecting">connecting</link> for more information 
+    about creating connections.
    </para>
   </section>
   <!-- }}} -->

reference/mongo/mongo/close.xml

@@ -4,7 +4,7 @@
 <refentry xml:id="mongo.close" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Mongo::close</refname>
-  <refpurpose>Closes this database connection</refpurpose>
+  <refpurpose>Closes this connection</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -16,61 +16,19 @@
   <para>
    This method does not need to be called, except in unusual 
    circumstances.  The driver will cleanly close the database 
-   connection when the Mongo object goes out of scope.
+   connection when this Mongo instance goes out of scope.
   </para>
   <para>
-   If you are using a service where objects do not go out of scope 
-   between requests, you may wish to call close() at the end of 
-   your program to keep old connections from hanging around.  
-   However, it is probably more efficient to take advantage of 
-   this fact and simply use a persistent connection, which will 
-   automatically create a connection if needed and use it for as 
-   many requests as the application server allows it to exist.
+   If objects do not go out of scope between requests, you may wish to call 
+   this method at the end of your program to keep old connections from hanging 
+   around.  However, it is probably more efficient use a persistent connection, 
+   which will automatically create a connection if needed and use it for as 
+   many requests as possible.
   </para>
   <para>
-   You may also wish to call close() if you are unsure of the 
-   state of a connection and wish to guarantee a new connection will 
-   happen.  For example:
+   If you are connected to a replica set, close() will only close the connection
+   to the primary.
   </para>
-
-  <informalexample>
-   <programlisting role="php">
-<![CDATA[
-<?php
-
-$mongo = new Mongo();
-
-/* do stuff where the db connection may be lost */
-
-/* if $mongo is already connected, does nothing */
-$mongo->connect(); 
-
-?>
-]]>
-   </programlisting>
-  </informalexample>
-
-  <para>
-    vs.
-  </para>
-
-  <informalexample>
-   <programlisting role="php">
-<![CDATA[
-<?php
-
-$mongo = new Mongo();
-
-/* do stuff where the db connection may be lost */
-
-/* guarantee a reconnection to the db server */
-$mongo->close();
-$mongo->connect(); 
-
-?>
-]]>
-   </programlisting>
-  </informalexample>
  </refsect1>
 
  <refsect1 role="parameters">

reference/mongo/mongocursor/info.xml

@@ -58,7 +58,7 @@
         returned by the server in the current batch), and 
         <literal>server</literal> (which server the query was sent 
         to&mdash;useful in conjunction with 
-        <function>MongoCursor::slaveOkay</function>.
+        <function>MongoCursor::slaveOkay</function>).
        </entry>
       </row>
      </tbody>

reference/mongo/mongocursor/slaveokay.xml

@@ -14,7 +14,43 @@
    <methodparam choice="opt"><type>boolean</type><parameter>okay</parameter><initializer>true</initializer></methodparam>
   </methodsynopsis>
   <para>
-   This method will override the static class variable <varname>slaveOkay</varname>.
+   Calling this will make the driver route reads to slaves if:
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      You are using a replica set and
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      You created a <classname>Mongo</classname> instance using the option
+      <literal>"replicaSet" => true and</literal>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      There is a healthy slave that can be reached by the driver.
+     </simpara>
+    </listitem>
+   </itemizedlist>
+   You can check which server was used for this query by calling 
+   <function>MongoCursor::info</function> after running the query.  It's
+   <literal>server</literal> field will show which server the query was sent to.
+  </para>
+  <para>
+   Note that you should use this function even if you do not use the automatic 
+   routing to slaves.  If you connect directly to a secondary in a replica set, 
+   you still need to call this function, which basically tells the database that
+   you are aware that you might be getting older data and you're okay with that.
+   If you do not call this, you'll get "not master" errors when you try to 
+   query.
+  </para>
+  <para>
+   This method will override the static class variable 
+   <varname>MongoCursor::slaveOkay</varname>.  It will also override 
+   <function>Mongo::setSlaveOkay</function>, 
+   <function>MongoDB::setSlaveOkay</function> and
+   <function>MongoCollection::setSlaveOkay</function>.
   </para>
  </refsect1>
 

reference/mongo/queries.xml

@@ -81,7 +81,11 @@ m2's slave is: ip1
 
    <para>
     If we continued to create new <classname>Mongo</classname>s, we should get a
-    fairly even distribution between ip1 and ip2.
+    fairly even distribution between ip1 and ip2.  Keep in mind that all 
+    secondaries listed by the <function>isMaster</function> command will be in
+    the pool of possible readers (even ones with priority 0 or slaveDelay set).
+    If you have certain servers you do not wish to read from, either route reads
+    manually or add the hidden option to the server's replica set configuration.
    </para>
 
    <para>