From 20c2e4631ae62b9922436213717dc4f6bc2cf89f Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@php.net>
Date: Wed, 28 May 2014 15:36:49 +0000
Subject: [PATCH] Rewrite MongoCollection::deleteIndex() documentation

https://jira.mongodb.org/browse/PHP-970

Attempted to clarify how string arguments are handled and touched up the code examples.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@333623 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../mongo/mongocollection/deleteindex.xml     | 72 +++++++++++--------
 1 file changed, 41 insertions(+), 31 deletions(-)

diff --git a/reference/mongo/mongocollection/deleteindex.xml b/reference/mongo/mongocollection/deleteindex.xml
index 1b9885ff18..bdd9f38fe2 100644
--- a/reference/mongo/mongocollection/deleteindex.xml
+++ b/reference/mongo/mongocollection/deleteindex.xml
@@ -21,49 +21,54 @@
 <?php
 
 public function deleteIndexes($keys) {
-  // toIndexString is a protected method that turns strings, arrays, and objs 
-  //into index names
-  $index = $this->toIndexString($keys);
+  $indexName = $this->toIndexString($keys);
 
-  return $this->db->command(array("deleteIndexes" => $this->getName(), 
-    "index" => $index));
+  return $this->db->command(array(
+    "deleteIndexes" => $this->getName(),
+    "index" => $indexName,
+  ));
 }
 
 ?>
 ]]>
   </programlisting>
   <para>
-   Each index, when created, is given a unique name.  This is generally user-set 
-   (with <function>MongoCollection::ensureIndex</function>'s "name" option) or
-   generated by the driver from a combination of key names and directions.  This
-   name is then used by <function>MongoCollection::deleteIndex</function> to
-   remove the function.
+   Each index is given a unique name when it is created. This is often generated
+   by the driver based on the index key(s) and order/type, but custom names may
+   also be specified with <function>MongoCollection::createIndex</function>'s
+   <literal>"name"</literal> option).
   </para>
   <para>
-   Unfortunately, the <function>MongoCollection::ensureIndex</function> 
-   generates slightly different names than the shell and, due to backwards 
-   compatibility issues, <function>MongoCollection::deleteIndex</function>
-   cannot delete custom-named indexes as well.  Thus, the best way to delete
-   indexes created in the shell or with custom names is to directly call the
-   <literal>deleteIndexes</literal> database command.
+   Unfortunately, <function>MongoCollection::deleteIndex</function> cannot
+   delete custom-named indexes due to a backwards compatibility issue. When a
+   string argument is provided, it is assumed to be the single field name in an
+   ascending index (e.g. the name <literal>"x_1"</literal> would be used for the
+   argument <literal>"x"</literal>). If an array or object is provided, an index
+   name is generated just as if that argument was passed to
+   <function>MongoCollection::createIndex</function>.
   </para>
   <para>
-   Thus, if you named an index "superfast query", you could only delete it
-   with the PHP driver by running:
+   In order to delete a custom-named index with the PHP driver, the
+   <literal>deleteIndexes</literal> database command must be used. For instance,
+   an index named "myIndex" could be deleted with the PHP driver by running:
   </para>
   <programlisting role="php">
 <![CDATA[
 <?php
 
-$db->command(array("deleteIndexes" => $collection->getName(), "index" => "superfast query"));
+$db->command(array(
+  "deleteIndexes" => $collection->getName(),
+  "index" => "myIndex",
+));
 
 ?>
 ]]>
   </programlisting>
   <para>
-   To find what an index is named, you can query the 
+   To determine the name of an index with the PHP driver, you can query the
    <literal>system.indexes</literal> collection of a database and look for the
-   <literal>name</literal> field.
+   <literal>"name"</literal> field of each result. The <literal>"ns"</literal>
+   field will indicate the collection to which each index belongs.
   </para>
  </refsect1>
 
@@ -77,10 +82,18 @@ $db->command(array("deleteIndexes" => $collection->getName(), "index" => "superf
      </term>
      <listitem>
       <para>
-       Field or fields from which to delete the index.
+       An array specifying the index's fields as its keys. For each field, the
+       value is either the index direction or
+       <link xlink:href="&url.mongodb.dochub.indexes.types;">index type</link>.
+       If specifying direction, specify <literal>1</literal> for ascending or
+       <literal>-1</literal> for descending.
+      </para>
+      <para>
+       If a string is provided, it is assumed to be the single field name in an
+       ascending index.
       </para>
      </listitem>
-    </varlistentry>   
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -102,21 +115,18 @@ $db->command(array("deleteIndexes" => $collection->getName(), "index" => "superf
    <programlisting role="php">
 <![CDATA[
 <?php
+
 $m = new MongoClient();
 $c = $m->example->indices;
 
-// create an index
-$c->ensureIndex(array("i"=>1));
-
-// remove a simple index
+// create and remove a simple index
+$c->createIndex(array("i"=>1));
 $c->deleteIndex("i");
 
-
-// create a multi-key index
+// create and remove a multi-key index
 $c->ensureIndex(array("j" => 1, "k" => 1));
-
-// remove a multi-key index
 $c->deleteIndex(array("j" => 1, "k" => 1));
+
 ?>
 ]]>
    </programlisting>