Added explanation of weird mongod js parsing behavior

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

reference/mongo/mongodb/execute.xml

@@ -38,6 +38,56 @@ public function execute($code, $args) {
 ]]>
    </programlisting>
   </para>
+  <para>
+   MongoDB implies a return statement if you have a single statement on a single
+   line. This can cause some unintuitive behavior.  For example, this returns 
+   "foo":
+  </para>
+  <programlisting role="php">
+<![CDATA[
+<?php
+
+$db->execute('"foo";');
+
+?>
+]]>
+  </programlisting>
+  <para>
+   However, these return &null;:
+  </para>
+  <programlisting role="php">
+<![CDATA[
+<?php
+
+$db->execute('"bar"; "foo";'); // more than one statement
+
+$db->execute('db.foo.count(
+);'); // more than one line
+
+?>
+]]>
+  </programlisting>
+  <para>
+   To avoid surprising behavior, it is best not to depend on MongoDB to decide 
+   what to return, but to explicitly state a return value. In the examples 
+   above, we can change them to:
+  </para>
+  <programlisting role="php">
+<![CDATA[
+<?php
+
+$db->execute('"bar"; return "foo";');
+
+$db->execute('return db.foo.count(
+);');
+
+?>
+]]>
+  </programlisting>
+  <para>
+   Now the first statement will return "foo" and the second statement will 
+   return a count of the "foo" collection.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">