From 88fb3e60e4165df620d3c8ead7111db54d38f8cd Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@php.net>
Date: Mon, 12 Aug 2013 18:55:16 +0000
Subject: [PATCH] Clarify doc/id param resolution for
 MongoCollection/DB::createDBRef()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@331115 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/mongocollection/createdbref.xml | 12 +++++++++---
 reference/mongo/mongodb/createdbref.xml         | 14 +++++++++-----
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/reference/mongo/mongocollection/createdbref.xml b/reference/mongo/mongocollection/createdbref.xml
index ce8f5bc61a..9bbdfe16e2 100644
--- a/reference/mongo/mongocollection/createdbref.xml
+++ b/reference/mongo/mongocollection/createdbref.xml
@@ -11,7 +11,7 @@
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>array</type><methodname>MongoCollection::createDBRef</methodname>
-   <methodparam><type>array</type><parameter>a</parameter></methodparam>
+   <methodparam><type>mixed</type><parameter>document_or_id</parameter></methodparam>
   </methodsynopsis>
  </refsect1>
 
@@ -21,11 +21,13 @@
    <variablelist>
     <varlistentry>
      <term>
-      <parameter>a</parameter>
+      <parameter>document_or_id</parameter>
      </term>
      <listitem>
       <para>
-       Object to which to create a reference.
+       If an array or object is given, its <literal>_id</literal> field will be
+       used as the reference ID. If a <classname>MongoId</classname> or scalar
+       is given, it will be used as the reference ID.
       </para>
      </listitem>
     </varlistentry>   
@@ -38,6 +40,10 @@
   <para>
    Returns a database reference array.
   </para>
+  <para>
+   If an array without an <literal>_id</literal> field was provided as the
+   <literal>document_or_id</literal> parameter, &null; will be returned.
+  </para>
  </refsect1>
 
  <refsect1 role="examples">
diff --git a/reference/mongo/mongodb/createdbref.xml b/reference/mongo/mongodb/createdbref.xml
index 3338c560da..57a9704594 100644
--- a/reference/mongo/mongodb/createdbref.xml
+++ b/reference/mongo/mongodb/createdbref.xml
@@ -12,7 +12,7 @@
   <methodsynopsis>
    <modifier>public</modifier> <type>array</type><methodname>MongoDB::createDBRef</methodname>
    <methodparam><type>string</type><parameter>collection</parameter></methodparam>
-   <methodparam><type>mixed</type><parameter>a</parameter></methodparam>
+   <methodparam><type>mixed</type><parameter>document_or_id</parameter></methodparam>
   </methodsynopsis>
   <para>
    This method is a flexible interface for creating database refrences (see
@@ -36,13 +36,13 @@
     </varlistentry>   
     <varlistentry>
      <term>
-      <parameter>a</parameter>
+      <parameter>document_or_id</parameter>
      </term>
      <listitem>
       <para>
-       Object or _id to which to create a reference.  If an object or
-       associative array is given, this will create a reference using
-       the <literal>_id</literal> field.
+       If an array or object is given, its <literal>_id</literal> field will be
+       used as the reference ID. If a <classname>MongoId</classname> or scalar
+       is given, it will be used as the reference ID.
       </para>
      </listitem>
     </varlistentry>   
@@ -55,6 +55,10 @@
   <para>
    Returns a database reference array.
   </para>
+  <para>
+   If an array without an <literal>_id</literal> field was provided as the
+   <literal>document_or_id</literal> parameter, &null; will be returned.
+  </para>
  </refsect1>
  <refsect1 role="examples">
   &reftitle.examples;