From 6b2eb216fd3b435212c79c31b4e024b6cd7c13e7 Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@php.net>
Date: Wed, 6 Aug 2014 19:41:45 +0000
Subject: [PATCH] Revise MongoLog class documentation

Rewrite intro documentation and move PHP notice tip to a note block. Add MongoLog::CON. Add changelog, deprecating old constants. Fix modifiers for class properties.

https://jira.mongodb.org/browse/PHP-1162


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@334512 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/mongolog.xml | 115 +++++++++++++++++++++++++----------
 1 file changed, 83 insertions(+), 32 deletions(-)

diff --git a/reference/mongo/mongolog.xml b/reference/mongo/mongolog.xml
index 014c4d9a5a..d815470dd8 100644
--- a/reference/mongo/mongolog.xml
+++ b/reference/mongo/mongolog.xml
@@ -13,17 +13,8 @@
    &reftitle.intro;
    <para>
     Logging can be used to get detailed information about what the driver is
-    doing. The logging mechanism as used by MongoLog emits all log messages
-    as a PHP notice. Depending on the server interface that you use,
-    that means that they will either be sent to strerr (with PHP-CLI), or
-    otherwise to the web server's error log. In order for log messages to
-    be output by PHP their level (E_NOTICE) does need to be configured to
-    be shown. That means the E_NOTICE bit needs to be part of PHP's
-    error_reporting level and that display_errors is set to 1.
-   </para>
-   <para>
-    Logging is turned off, by default. This class allows you to turn on
-    specific levels of logging for specific parts of the driver. Some examples:
+    doing. Logging is disabled by default, but this class allows you to activate
+    specific levels of logging for various parts of the driver. Some examples:
    </para>
    <programlisting role="php">
 <![CDATA[
@@ -37,13 +28,24 @@ MongoLog::setModule(MongoLog::ALL); // all parts of the driver
 MongoLog::setLevel(MongoLog::INFO);
 MongoLog::setModule(MongoLog::RS);
 
-// print info- and server tuning-level events from replica sets and connection pooling
+// print info- and diagnostic-level events for replica sets and connections
 MongoLog::setLevel(MongoLog::INFO|MongoLog::FINE);
-MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
+MongoLog::setModule(MongoLog::RS|MongoLog::CON);
 
 ?>
 ]]>
    </programlisting>
+   <note>
+    <para>
+     By default, MongoLog emits all log messages as PHP notices. Depending
+     on the <acronym>SAPI</acronym> you use, messages may be sent to
+     <literal>stderr</literal> (for <acronym>CLI</acronym>) or the web server's
+     error log. If, after configuring MongoLog, log messages are not appearing
+     as expected, ensure that the <constant>E_NOTICE</constant> bit is included
+     in <link linkend="ini.error-reporting">error_reporting</link> and that
+     <link linkend="ini.display-errors">display_errors</link> is on.
+    </para>
+   </note>
   </section>
 <!-- }}} -->
 
@@ -107,6 +109,12 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
      <modifier>const</modifier>
      <type>int</type>
      <varname linkend="mongolog.constants.pool">MongoLog::POOL</varname>
+     <initializer>1</initializer>
+    </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>const</modifier>
+     <type>int</type>
+     <varname linkend="mongolog.constants.con">MongoLog::CON</varname>
      <initializer>2</initializer>
     </fieldsynopsis>
     <fieldsynopsis>
@@ -130,13 +138,20 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
 
     <classsynopsisinfo role="comment">Fields</classsynopsisinfo>
     <fieldsynopsis>
-     <modifier>public</modifier>
-     <modifier></modifier>
+     <modifier>private</modifier>
+     <modifier>static</modifier>
+     <type>int</type>
+     <varname>callback</varname>
+    </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>private</modifier>
+     <modifier>static</modifier>
      <type>int</type>
      <varname>level</varname>
     </fieldsynopsis>
     <fieldsynopsis>
-     <modifier>public</modifier>
+     <modifier>private</modifier>
+     <modifier>static</modifier>
      <type>int</type>
      <varname>module</varname>
     </fieldsynopsis>
@@ -163,7 +178,7 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
       <term><constant>MongoLog::NONE</constant></term>
       <listitem>
        <simpara>
-        Constant for turning logging off.
+        Log nothing.
        </simpara>
       </listitem>
      </varlistentry>
@@ -171,7 +186,7 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
       <term><constant>MongoLog::ALL</constant></term>
       <listitem>
        <simpara>
-        Constant for logging everything.
+        Log everything.
        </simpara>
       </listitem>
      </varlistentry>
@@ -188,8 +203,8 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
       <term><constant>MongoLog::WARNING</constant></term>
       <listitem>
        <simpara>
-        This will print log messages about somewhat exceptional but
-        not-quite-exception-worthy happenings.
+        Log events that are somewhat exceptional, but not quite worthy of an
+        actual exception (e.g. recoverable connection errors).
        </simpara>
       </listitem>
      </varlistentry>
@@ -197,8 +212,8 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
       <term><constant>MongoLog::INFO</constant></term>
       <listitem>
        <simpara>
-        Logs events that may be of interest to administrators, but are not
-        particularly noteworthy.
+        Log events that may be of interest to administrators, but are not
+        particularly noteworthy (e.g. option parsing, authentication steps).
        </simpara>
       </listitem>
      </varlistentry>
@@ -206,8 +221,9 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
       <term><constant>MongoLog::FINE</constant></term>
       <listitem>
        <simpara>
-        Logs most events that the driver performs. Depending on the module being
-        logged, this can be extremely noisy and is primarily for debugging.
+        Log most events that the driver performs (e.g. server selection, socket
+        communication). Depending on the module being logged, this can be
+        extremely noisy and is primarily useful for debugging.
        </simpara>
       </listitem>
      </varlistentry>
@@ -220,11 +236,20 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
      These constants can be used by <function>MongoLog::setModule</function>.
     </para>
     <variablelist>
+     <varlistentry xml:id="mongolog.constants.con">
+      <term><constant>MongoLog::CON</constant></term>
+      <listitem>
+       <simpara>
+        Log connection activity. Creating new connections, authentication,
+        pinging, timeouts, etc.
+       </simpara>
+      </listitem>
+     </varlistentry>
      <varlistentry xml:id="mongolog.constants.io">
       <term><constant>MongoLog::IO</constant></term>
       <listitem>
        <simpara>
-        Logs traffic to/from the database. Unless your program is trivial, this
+        Log traffic to/from the database. Unless your program is trivial, this
         will create an enormous number of log messages.
        </simpara>
       </listitem>
@@ -233,7 +258,8 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
       <term><constant>MongoLog::PARSE</constant></term>
       <listitem>
        <simpara>
-        Log server string parsing.
+        Log parsing of the connection string and options when constructing
+        <classname>MongoClient</classname>.
        </simpara>
       </listitem>
      </varlistentry>
@@ -241,8 +267,8 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
       <term><constant>MongoLog::POOL</constant></term>
       <listitem>
        <simpara>
-        Log connection pool activity. Creating new connections, reusing
-        connections, and closing connections.
+        Previously used to log connection pool activity. This option is now a
+        deprecated alias of <constant>MongoLog::RS</constant>.
        </simpara>
       </listitem>
      </varlistentry>
@@ -250,8 +276,7 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
       <term><constant>MongoLog::RS</constant></term>
       <listitem>
        <simpara>
-        Log replica set activity. Failovers, pinging, chosing secondaries to
-        read from, etc.
+        Log replica set activity. Failovers, read preference selection, etc.
        </simpara>
       </listitem>
      </varlistentry>
@@ -259,8 +284,8 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
       <term><constant>MongoLog::SERVER</constant></term>
       <listitem>
        <simpara>
-        Log server status changes. Detecting primary, secondary and
-        duplication detection.
+        Previously used to log server status changes. This option is deprecated
+        in favor of <constant>MongoLog::RS</constant>.
        </simpara>
       </listitem>
      </varlistentry>
@@ -268,6 +293,32 @@ MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
    </section>
   </section>
 
+  <section role="changelog">
+   &reftitle.changelog;
+   <para>
+    <informaltable>
+     <tgroup cols="2">
+      <thead>
+       <row>
+        <entry>&Version;</entry>
+        <entry>&Description;</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+        <entry>1.3.0</entry>
+        <entry>
+         Added <constant>MongoLog::CON</constant> and deprecated
+         <constant>MongoLog::POOL</constant> and
+         <constant>MongoLog::SERVER</constant>.
+        </entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </informaltable>
+   </para>
+  </section>
+
  </partintro>
 
  &reference.mongo.entities.mongolog;