From 8ad788358deb7287043bea8eddc424ec72ea9c6e Mon Sep 17 00:00:00 2001
From: Derick Rethans <derick@php.net>
Date: Thu, 29 Dec 2011 15:45:00 +0000
Subject: [PATCH] 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 | 22 +++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/reference/mongo/mongocollection/findone.xml b/reference/mongo/mongocollection/findone.xml
index 7e9a88d125..739d93a561 100644
--- a/reference/mongo/mongocollection/findone.xml
+++ b/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>