From 255568b4c9caabd957bee9cafd3faaa23bef5d8c Mon Sep 17 00:00:00 2001
From: Derick Rethans <derick@php.net>
Date: Thu, 29 Dec 2011 14:51:09 +0000
Subject: [PATCH] Explain the fields array better.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@321508 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/mongocursor/sort.xml | 48 +++++++++-------------------
 1 file changed, 15 insertions(+), 33 deletions(-)

diff --git a/reference/mongo/mongocursor/sort.xml b/reference/mongo/mongocursor/sort.xml
index 5af1c92fc8..fda21fb335 100644
--- a/reference/mongo/mongocursor/sort.xml
+++ b/reference/mongo/mongocursor/sort.xml
@@ -25,7 +25,15 @@
      </term>
      <listitem>
       <para>
-       The fields by which to sort.
+       An array of fields by which to sort. Each element in the array has as
+       key the field name, and as value either <literal>1</literal> for
+       ascending sort, or <literal>-1</literal> for descending sort.
+      </para>
+      <para>
+       Each result is first sorted on the first field in the array, then (if
+       it exists) on the second field in the array, etc. This means that the
+       order of the fields in the <parameter>fields</parameter> array is
+       important. See also the examples section.
       </para>
      </listitem>
     </varlistentry>   
@@ -36,7 +44,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;  
   <para>
-   Returns this cursor.
+   Returns the same cursor that this method was called on.
   </para>
  </refsect1>
 
@@ -47,32 +55,6 @@
   </para>
  </refsect1>
 
- <refsect1 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>
-        The <parameter>options</parameter> parameter does no longer accept
-        just a boolean to signify a safe insert. Instead, this now has to be done
-        with <literal>array('safe' => true)</literal>.
-       </entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </informaltable>
-  </para>
- </refsect1>
-
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
@@ -80,16 +62,16 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-// sort x ascending
+// Sort on field x, ascending
 $cursor->sort(array('x' => 1));
 
-// the associative array is ordered, for instance, these two 
-// examples might yield different results:
+// The order in the associative array is important. For instance, these two
+// examples will yield different results:
 
-// sort date ascending and age descending
+// Sort on date ascending and age descending
 $cursor->sort(array('date' => 1, 'age' => -1));
 
-// sort age descending and date ascending
+// Sort on age descending and date ascending
 $cursor->sort(array('age' => -1, 'date' => 1));
 ?>
 ]]>