Fix phpdoc comments

lib/Mongo/MongoDB.php

@@ -68,7 +68,7 @@ class MongoDB
 
     /**
      * @return \MongoDB\Database
-     * @internal
+     * @internal This method is not part of the ext-mongo API
      */
     public function getDb()
     {
@@ -77,6 +77,7 @@ class MongoDB
 
     /**
      * The name of this database
+     *
      * @link http://www.php.net/manual/en/mongodb.--tostring.php
      * @return string Returns this database's name.
      */
@@ -115,11 +116,10 @@ class MongoDB
     }
 
     /**
-     * (PECL mongo &gt;= 1.3.0)<br/>
-     * @link http://www.php.net/manual/en/mongodb.getcollectionnames.php
      * Get all collections from this database
-     * @return array Returns the names of the all the collections in the database as an
-     * {@link http://www.php.net/manual/en/language.types.array.php array}.
+     *
+     * @link http://www.php.net/manual/en/mongodb.getcollectionnames.php
+     * @return array Returns the names of the all the collections in the database as an array
      */
     public function getCollectionNames(array $options = [])
     {
@@ -147,10 +147,10 @@ class MongoDB
     }
 
     /**
-     * (PECL mongo &gt;= 0.9.0)<br/>
      * Fetches toolkit for dealing with files stored in this database
+     *
      * @link http://www.php.net/manual/en/mongodb.getgridfs.php
-     * @param string $prefix [optional] The prefix for the files and chunks collections.
+     * @param string $prefix The prefix for the files and chunks collections.
      * @return MongoGridFS Returns a new gridfs object for this database.
      */
     public function getGridFS($prefix = "fs")
@@ -159,8 +159,8 @@ class MongoDB
     }
 
     /**
-     * (PECL mongo &gt;= 0.9.0)<br/>
      * Gets this database's profiling level
+     *
      * @link http://www.php.net/manual/en/mongodb.getprofilinglevel.php
      * @return int Returns the profiling level.
      */
@@ -172,8 +172,8 @@ class MongoDB
     }
 
     /**
-     * (PECL mongo &gt;= 0.9.0)<br/>
      * Sets this database's profiling level
+     *
      * @link http://www.php.net/manual/en/mongodb.setprofilinglevel.php
      * @param int $level Profiling level.
      * @return int Returns the previous profiling level.
@@ -186,8 +186,8 @@ class MongoDB
     }
 
     /**
-     * (PECL mongo &gt;= 0.9.0)<br/>
      * Drops this database
+     *
      * @link http://www.php.net/manual/en/mongodb.drop.php
      * @return array Returns the database response.
      */
@@ -198,6 +198,7 @@ class MongoDB
 
     /**
      * Repairs and compacts this database
+     *
      * @link http://www.php.net/manual/en/mongodb.repair.php
      * @param bool $preserve_cloned_files [optional] <p>If cloned files should be kept if the repair fails.</p>
      * @param bool $backup_original_files [optional] <p>If original files should be backed up.</p>
@@ -209,14 +210,12 @@ class MongoDB
     }
 
     /**
-     * (PECL mongo &gt;= 0.9.0)<br/>
      * Gets a collection
+     *
      * @link http://www.php.net/manual/en/mongodb.selectcollection.php
      * @param string $name <b>The collection name.</b>
      * @throws Exception if the collection name is invalid.
-     * @return MongoCollection <p>
-     * Returns a new collection object.
-     * </p>
+     * @return MongoCollection Returns a new collection object.
      */
     public function selectCollection($name)
     {
@@ -225,37 +224,11 @@ class MongoDB
 
     /**
      * Creates a collection
+     *
      * @link http://www.php.net/manual/en/mongodb.createcollection.php
      * @param string $name The name of the collection.
-     * @param array $options [optional] <p>
-     * <p>
-     * An array containing options for the collections. Each option is its own
-     * element in the options array, with the option name listed below being
-     * the key of the element. The supported options depend on the MongoDB
-     * server version. At the moment, the following options are supported:
-     * </p>
-     * <p>
-     * <b>capped</b>
-     * <p>
-     * If the collection should be a fixed size.
-     * </p>
-     * </p>
-     * <p>
-     * <b>size</b>
-     * <p>
-     * If the collection is fixed size, its size in bytes.</p></p>
-     * <p><b>max</b>
-     * <p>If the collection is fixed size, the maximum number of elements to store in the collection.</p></p>
-     * <i>autoIndexId</i>
-     *
-     * <p>
-     * If capped is <b>TRUE</b> you can specify <b>FALSE</b> to disable the
-     * automatic index created on the <em>_id</em> field.
-     * Before MongoDB 2.2, the default value for
-     * <em>autoIndexId</em> was <b>FALSE</b>.
-     * </p>
-     * </p>
-     * @return MongoCollection <p>Returns a collection object representing the new collection.</p>
+     * @param array $options
+     * @return MongoCollection Returns a collection object representing the new collection.
      */
     public function createCollection($name, $options)
     {
@@ -264,23 +237,28 @@ class MongoDB
     }
 
     /**
-     * (PECL mongo &gt;= 0.9.0)<br/>
-     * @deprecated Use MongoCollection::drop() instead.
      * Drops a collection
+     *
      * @link http://www.php.net/manual/en/mongodb.dropcollection.php
      * @param MongoCollection|string $coll MongoCollection or name of collection to drop.
      * @return array Returns the database response.
+     *
+     * @deprecated Use MongoCollection::drop() instead.
      */
     public function dropCollection($coll)
     {
+        if ($coll instanceof MongoCollection) {
+            $coll = $coll->getName();
+        }
+
         return $this->db->dropCollection((string) $coll);
     }
 
     /**
-     * (PECL mongo &gt;= 0.9.0)<br/>
      * Get a list of collections in this database
+     *
      * @link http://www.php.net/manual/en/mongodb.listcollections.php
-     * @param bool $includeSystemCollections [optional] <p>Include system collections.</p>
+     * @param array $options
      * @return array Returns a list of MongoCollections.
      */
     public function listCollections(array $options = [])
@@ -289,20 +267,12 @@ class MongoDB
     }
 
     /**
-     * (PECL mongo &gt;= 0.9.0)<br/>
      * Creates a database reference
+     *
      * @link http://www.php.net/manual/en/mongodb.createdbref.php
      * @param string $collection The collection to which the database reference will point.
-     * @param mixed $document_or_id <p>
-     * If an array or object is given, its <em>_id</em> field will be
-     * used as the reference ID. If a {@see MongoId} or scalar
-     * is given, it will be used as the reference ID.
-     * </p>
-     * @return array <p>Returns a database reference array.</p>
-     * <p>
-     * If an array without an <em>_id</em> field was provided as the
-     * <em>document_or_id</em> parameter, <b>NULL</b> will be returned.
-     * </p>
+     * @param mixed $document_or_id
+     * @return array Returns a database reference array.
      */
     public function createDBRef($collection, $document_or_id)
     {
@@ -329,8 +299,8 @@ class MongoDB
 
 
     /**
-     * (PECL mongo &gt;= 0.9.0)<br/>
      * Fetches the document pointed to by a database reference
+     *
      * @link http://www.php.net/manual/en/mongodb.getdbref.php
      * @param array $ref A database reference.
      * @return array Returns the document pointed to by the reference.
@@ -355,20 +325,11 @@ class MongoDB
 
     /**
      * Execute a database command
+     *
      * @link http://www.php.net/manual/en/mongodb.command.php
      * @param array $data The query to send.
-     * @param array() $options [optional] <p>
-     * This parameter is an associative array of the form
-     * <em>array("optionname" =&gt; &lt;boolean&gt;, ...)</em>. Currently
-     * supported options are:
-     * </p><ul>
-     * <li><p><em>"timeout"</em></p><p>Deprecated alias for <em>"socketTimeoutMS"</em>.</p></li>
-     * </ul>
+     * @param array $options
      * @return array Returns database response.
-     * Every database response is always maximum one document,
-     * which means that the result of a database command can never exceed 16MB.
-     * The resulting document's structure depends on the command,
-     * but most results will have the ok field to indicate success or failure and results containing an array of each of the resulting documents.
      */
     public function command(array $data, $options = [], &$hash = null)
     {
@@ -431,25 +392,12 @@ class MongoDB
     }
 
     /**
-     * (PECL mongo &gt;= 1.0.1)<br/>
      * Log in to this database
+     *
      * @link http://www.php.net/manual/en/mongodb.authenticate.php
      * @param string $username The username.
      * @param string $password The password (in plaintext).
-     * @return array <p>Returns database response. If the login was successful, it will return 1.</p>
-     * <p>
-     * <span style="color: #0000BB">&lt;?php<br></span><span style="color: #007700">array(</span><span style="color: #DD0000">"ok"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">);<br></span><span style="color: #0000BB">?&gt;</span>
-     * </span>
-     * </code></div>
-     * </div>
-     * </p>
-     * <p> If something went wrong, it will return </p>
-     * <p>
-     * <div class="example-contents">
-     * <div class="phpcode"><code><span style="color: #000000">
-     * <span style="color: #0000BB">&lt;?php<br></span><span style="color: #007700">array(</span><span style="color: #DD0000">"ok"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">0</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"errmsg"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"auth&nbsp;fails"</span><span style="color: #007700">);<br></span><span style="color: #0000BB">?&gt;</span></p>
-     *         <p>("auth fails" could be another message, depending on database version and
-     *         what went wrong)</p>
+     * @return array Returns database response. If the login was successful, it will return 1.
      */
     public function authenticate($username, $password)
     {