Explain fields for querying and return a bit better. Also add a warning for the

"$" issue and add the difference between find() and findOne().


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

reference/mongo/mongocollection/findone.xml

@@ -14,6 +14,11 @@
    <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>
   </methodsynopsis>
+  <para>
+   As opposed to <function>MongoCollection::find</function>, this method
+   will return only the <emphasis>first</emphasis> result from the result set,
+   and not a <class>MongoCursor</class> that can be iterated over.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -26,8 +31,19 @@
      </term>
      <listitem>
       <para>
-       The fields for which to search.
+       The fields for which to search. MongoDB's query language is quite
+       extensive. The PHP driver will in almost all cases pass the query
+       straight through to the server, so reading the MongoDB core docs on
+       <link xlink:href="&url.mongodb.dochub.find;">find</link> is a good idea.
       </para>
+      <warning>
+       <para>
+        Please make sure that for all special query operaters (starting with
+        <literal>$</literal>) you use single quotes so that PHP doesn't try to
+        replace <literal>"$exists"</literal> with the value of the variable
+        <literal>$exists</literal>.
+       </para>
+      </warning>
      </listitem>
     </varlistentry>   
     <varlistentry>
@@ -36,7 +52,9 @@
      </term>
      <listitem>
       <para>
-       Fields of the results to return.
+       Fields of the results to return. The array is in the format
+       <literal>array('fieldname' => true, 'fieldname2' => true)</literal>.
+       The <literal>_id</literal> field is always returned.
       </para>
      </listitem>
     </varlistentry>