Merge pull request #125 from adrienbrault/master

PHPDoc blocks improvments + 1 CS Fix

lib/Doctrine/DBAL/Cache/ResultCacheStatement.php

@@ -151,23 +151,6 @@ class ResultCacheStatement implements \IteratorAggregate, ResultStatement
      *                                      This value must be one of the Query::HYDRATE_* constants,
      *                                      defaulting to Query::HYDRATE_BOTH
      *
-     * @param integer $cursorOrientation    For a PDOStatement object representing a scrollable cursor,
-     *                                      this value determines which row will be returned to the caller.
-     *                                      This value must be one of the Query::HYDRATE_ORI_* constants, defaulting to
-     *                                      Query::HYDRATE_ORI_NEXT. To request a scrollable cursor for your
-     *                                      PDOStatement object,
-     *                                      you must set the PDO::ATTR_CURSOR attribute to Doctrine::CURSOR_SCROLL when you
-     *                                      prepare the SQL statement with Doctrine_Adapter_Interface->prepare().
-     *
-     * @param integer $cursorOffset         For a PDOStatement object representing a scrollable cursor for which the
-     *                                      $cursorOrientation parameter is set to Query::HYDRATE_ORI_ABS, this value specifies
-     *                                      the absolute number of the row in the result set that shall be fetched.
-     *
-     *                                      For a PDOStatement object representing a scrollable cursor for
-     *                                      which the $cursorOrientation parameter is set to Query::HYDRATE_ORI_REL, this value
-     *                                      specifies the row to fetch relative to the cursor position before
-     *                                      PDOStatement->fetch() was called.
-     *
      * @return mixed
      */
     public function fetch($fetchStyle = PDO::FETCH_BOTH)
@@ -201,9 +184,6 @@ class ResultCacheStatement implements \IteratorAggregate, ResultStatement
      *                                      This value must be one of the Query::HYDRATE_* constants,
      *                                      defaulting to Query::HYDRATE_BOTH
      *
-     * @param integer $columnIndex          Returns the indicated 0-indexed column when the value of $fetchStyle is
-     *                                      Query::HYDRATE_COLUMN. Defaults to 0.
-     *
      * @return array
      */
     public function fetchAll($fetchStyle = PDO::FETCH_BOTH)

lib/Doctrine/DBAL/Connection.php

@@ -90,22 +90,22 @@ class Connection implements DriverConnection
     /**
      * The wrapped driver connection.
      *
-     * @var Doctrine\DBAL\Driver\Connection
+     * @var \Doctrine\DBAL\Driver\Connection
      */
     protected $_conn;
 
     /**
-     * @var Doctrine\DBAL\Configuration
+     * @var \Doctrine\DBAL\Configuration
      */
     protected $_config;
 
     /**
-     * @var Doctrine\Common\EventManager
+     * @var \Doctrine\Common\EventManager
      */
     protected $_eventManager;
 
     /**
-     * @var Doctrine\DBAL\Query\ExpressionBuilder
+     * @var \Doctrine\DBAL\Query\ExpressionBuilder
      */
     protected $_expr;
 
@@ -148,21 +148,21 @@ class Connection implements DriverConnection
      * The DatabasePlatform object that provides information about the
      * database platform used by the connection.
      *
-     * @var Doctrine\DBAL\Platforms\AbstractPlatform
+     * @var \Doctrine\DBAL\Platforms\AbstractPlatform
      */
     protected $_platform;
 
     /**
      * The schema manager.
      *
-     * @var Doctrine\DBAL\Schema\SchemaManager
+     * @var \Doctrine\DBAL\Schema\AbstractSchemaManager
      */
     protected $_schemaManager;
 
     /**
      * The used DBAL driver.
      *
-     * @var Doctrine\DBAL\Driver
+     * @var \Doctrine\DBAL\Driver
      */
     protected $_driver;
 
@@ -322,7 +322,7 @@ class Connection implements DriverConnection
     /**
      * Gets the ExpressionBuilder for the connection.
      *
-     * @return \Doctrine\DBAL\Query\ExpressionBuilder
+     * @return \Doctrine\DBAL\Query\Expression\ExpressionBuilder
      */
     public function getExpressionBuilder()
     {
@@ -419,8 +419,8 @@ class Connection implements DriverConnection
     /**
      * Executes an SQL DELETE statement on a table.
      *
-     * @param string $table The name of the table on which to delete.
-     * @param array $identifier The deletion criteria. An associateve array containing column-value pairs.
+     * @param string $tableName The name of the table on which to delete.
+     * @param array $identifier The deletion criteria. An associative array containing column-value pairs.
      * @return integer The number of affected rows.
      */
     public function delete($tableName, array $identifier)
@@ -454,6 +454,7 @@ class Connection implements DriverConnection
      * Sets the transaction isolation level.
      *
      * @param integer $level The level to set.
+     * @return integer
      */
     public function setTransactionIsolation($level)
     {
@@ -475,7 +476,8 @@ class Connection implements DriverConnection
     /**
      * Executes an SQL UPDATE statement on a table.
      *
-     * @param string $table The name of the table to update.
+     * @param string $tableName The name of the table to update.
+     * @param array $data
      * @param array $identifier The update criteria. An associative array containing column-value pairs.
      * @param array $types Types of the merged $data and $identifier arrays in that order.
      * @return integer The number of affected rows.
@@ -500,7 +502,7 @@ class Connection implements DriverConnection
     /**
      * Inserts a table row with specified data.
      *
-     * @param string $table The name of the table to insert data into.
+     * @param string $tableName The name of the table to insert data into.
      * @param array $data An associative array containing column-value pairs.
      * @param array $types Types of the inserted data.
      * @return integer The number of affected rows.
@@ -863,7 +865,7 @@ class Connection implements DriverConnection
     /**
      * Set if nested transactions should use savepoints
      *
-     * @param boolean
+     * @param boolean $nestTransactionsWithSavepoints
      * @return void
      */
     public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
@@ -1151,7 +1153,7 @@ class Connection implements DriverConnection
      * Binds a set of parameters, some or all of which are typed with a PDO binding type
      * or DBAL mapping type, to a given statement.
      *
-     * @param $stmt The statement to bind the values to.
+     * @param string $stmt The statement to bind the values to.
      * @param array $params The map/list of named/positional parameters.
      * @param array $types The parameter types (PDO binding types or DBAL mapping types).
      * @internal Duck-typing used on the $stmt parameter to support driver statements as well as
@@ -1213,7 +1215,7 @@ class Connection implements DriverConnection
     /**
      * Create a new instance of a SQL query builder.
      *
-     * @return Query\QueryBuilder
+     * @return \Doctrine\DBAL\Query\QueryBuilder
      */
     public function createQueryBuilder()
     {

lib/Doctrine/DBAL/Driver.php

@@ -51,7 +51,7 @@ interface Driver
      * database schema of the platform this driver connects to.
      *
      * @param  \Doctrine\DBAL\Connection $conn
-     * @return \Doctrine\DBAL\SchemaManager
+     * @return \Doctrine\DBAL\Schema\AbstractSchemaManager
      */
     public function getSchemaManager(Connection $conn);
 

lib/Doctrine/DBAL/Driver/ResultStatement.php

@@ -62,23 +62,6 @@ interface ResultStatement extends \Traversable
      *                                      This value must be one of the Query::HYDRATE_* constants,
      *                                      defaulting to Query::HYDRATE_BOTH
      *
-     * @param integer $cursorOrientation    For a PDOStatement object representing a scrollable cursor,
-     *                                      this value determines which row will be returned to the caller.
-     *                                      This value must be one of the Query::HYDRATE_ORI_* constants, defaulting to
-     *                                      Query::HYDRATE_ORI_NEXT. To request a scrollable cursor for your
-     *                                      PDOStatement object,
-     *                                      you must set the PDO::ATTR_CURSOR attribute to Doctrine::CURSOR_SCROLL when you
-     *                                      prepare the SQL statement with Doctrine_Adapter_Interface->prepare().
-     *
-     * @param integer $cursorOffset         For a PDOStatement object representing a scrollable cursor for which the
-     *                                      $cursorOrientation parameter is set to Query::HYDRATE_ORI_ABS, this value specifies
-     *                                      the absolute number of the row in the result set that shall be fetched.
-     *
-     *                                      For a PDOStatement object representing a scrollable cursor for
-     *                                      which the $cursorOrientation parameter is set to Query::HYDRATE_ORI_REL, this value
-     *                                      specifies the row to fetch relative to the cursor position before
-     *                                      PDOStatement->fetch() was called.
-     *
      * @return mixed
      */
     function fetch($fetchStyle = PDO::FETCH_BOTH);
@@ -90,9 +73,6 @@ interface ResultStatement extends \Traversable
      *                                      This value must be one of the Query::HYDRATE_* constants,
      *                                      defaulting to Query::HYDRATE_BOTH
      *
-     * @param integer $columnIndex          Returns the indicated 0-indexed column when the value of $fetchStyle is
-     *                                      Query::HYDRATE_COLUMN. Defaults to 0.
-     *
      * @return array
      */
     function fetchAll($fetchStyle = PDO::FETCH_BOTH);

lib/Doctrine/DBAL/Driver/Statement.php

@@ -61,7 +61,7 @@ interface Statement extends ResultStatement
      * of stored procedures that return data as output parameters, and some also as input/output
      * parameters that both send in data and are updated to receive it.
      *
-     * @param mixed $param          Parameter identifier. For a prepared statement using named placeholders,
+     * @param mixed $column         Parameter identifier. For a prepared statement using named placeholders,
      *                              this will be a parameter name of the form :name. For a prepared statement
      *                              using question mark placeholders, this will be the 1-indexed position of the parameter
      *

lib/Doctrine/DBAL/Platforms/AbstractPlatform.php

@@ -226,6 +226,8 @@ abstract class AbstractPlatform
 
     /**
      * Gets the SQL Snippet used to declare a BLOB column type.
+     *
+     * @param array $field
      */
     abstract public function getBlobTypeDeclarationSQL(array $field);
 
@@ -269,11 +271,11 @@ abstract class AbstractPlatform
         }
 
         $dbType = strtolower($dbType);
-        if (isset($this->doctrineTypeMapping[$dbType])) {
-            return $this->doctrineTypeMapping[$dbType];
-        } else {
+        if (!isset($this->doctrineTypeMapping[$dbType])) {
             throw new \Doctrine\DBAL\DBALException("Unknown database type ".$dbType." requested, " . get_class($this) . " may not support it.");
         }
+
+        return $this->doctrineTypeMapping[$dbType];
     }
 
     /**
@@ -306,7 +308,7 @@ abstract class AbstractPlatform
      * Is it necessary for the platform to add a parsable type comment to allow reverse engineering the given type?
      *
      * @param Type $doctrineType
-     * @return bool
+     * @return boolean
      */
     public function isCommentedDoctrineType(Type $doctrineType)
     {
@@ -502,6 +504,7 @@ abstract class AbstractPlatform
      *
      * Note: Not SQL92, but common functionality
      *
+     * @param string $column
      * @return string
      */
     public function getMd5Expression($column)
@@ -512,8 +515,7 @@ abstract class AbstractPlatform
     /**
      * Returns the length of a text field.
      *
-     * @param string $expression1
-     * @param string $expression2
+     * @param string $column
      * @return string
      */
     public function getLengthExpression($column)
@@ -535,7 +537,8 @@ abstract class AbstractPlatform
     /**
      * Rounds a numeric field to the number of decimals specified.
      *
-     * @param string $expression1
+     * @param string $column
+     * @param integer $decimals
      * @return string
      */
     public function getRoundExpression($column, $decimals = 0)
@@ -633,9 +636,9 @@ abstract class AbstractPlatform
     /**
      * returns the position of the first occurrence of substring $substr in string $str
      *
-     * @param string $substr    literal string to find
      * @param string  $str       literal string
-     * @param int    $pos       position to start at, beginning of string by default
+     * @param string  $substr    literal string to find
+     * @param integer $startPos  position to start at, beginning of string by default
      * @return integer
      */
     public function getLocateExpression($str, $substr, $startPos = false)
@@ -699,6 +702,7 @@ abstract class AbstractPlatform
      *   ->where($e->eq('id', $e->not('null'));
      * </code>
      *
+     * @param string $expression
      * @return string a logical expression
      */
     public function getNotExpression($expression)
@@ -716,7 +720,7 @@ abstract class AbstractPlatform
      * These expressions will be matched against the first parameter.
      *
      * @param string $column                the value that should be matched against
-     * @param string|array(string)  values that will be matched against $column
+     * @param string|array(string) $values  values that will be matched against $column
      * @return string logical expression
      */
     public function getInExpression($column, $values)
@@ -1209,7 +1213,7 @@ abstract class AbstractPlatform
     /**
      * Gets the SQL to create a constraint on a table on this platform.
      *
-     * @param Constraint $constraint
+     * @param \Doctrine\DBAL\Schema\Constraint $constraint
      * @param string|Table $table
      * @return string
      */
@@ -1313,7 +1317,7 @@ abstract class AbstractPlatform
     /**
      * Quotes a string so that it can be safely used as a table or column name,
      * even if it is a reserved word of the platform. This also detects identifier
-     * chains seperated by dot and quotes them independently.
+     * chains separated by dot and quotes them independently.
      *
      * NOTE: Just because you CAN use quoted identifiers doesn't mean
      * you SHOULD use them.  In general, they end up causing way more
@@ -1333,7 +1337,7 @@ abstract class AbstractPlatform
     }
 
     /**
-     * Quote a single identifier (no dot chain seperation)
+     * Quote a single identifier (no dot chain separation)
      *
      * @param string $str
      * @return string
@@ -1380,6 +1384,7 @@ abstract class AbstractPlatform
      * @param Column $column
      * @param TableDiff $diff
      * @param array $columnSql
+     * @return boolean
      */
     protected function onSchemaAlterTableAddColumn(Column $column, TableDiff $diff, &$columnSql)
     {
@@ -1403,6 +1408,7 @@ abstract class AbstractPlatform
      * @param Column $column
      * @param TableDiff $diff
      * @param array $columnSql
+     * @return boolean
      */
     protected function onSchemaAlterTableRemoveColumn(Column $column, TableDiff $diff, &$columnSql)
     {
@@ -1426,6 +1432,7 @@ abstract class AbstractPlatform
      * @param ColumnDiff $columnDiff
      * @param TableDiff $diff
      * @param array $columnSql
+     * @return boolean
      */
     protected function onSchemaAlterTableChangeColumn(ColumnDiff $columnDiff, TableDiff $diff, &$columnSql)
     {
@@ -1450,6 +1457,7 @@ abstract class AbstractPlatform
      * @param Column $column
      * @param TableDiff $diff
      * @param array $columnSql
+     * @return boolean
      */
     protected function onSchemaAlterTableRenameColumn($oldColumnName, Column $column, TableDiff $diff, &$columnSql)
     {
@@ -1470,7 +1478,8 @@ abstract class AbstractPlatform
     }
     /**
      * @param TableDiff $diff
-     * @param array $columnSql
+     * @param array $qql
+     * @return boolean
      */
     protected function onSchemaAlterTable(TableDiff $diff, &$sql)
     {
@@ -1777,6 +1786,7 @@ abstract class AbstractPlatform
      * e.g. when a field has the "columnDefinition" keyword.
      * Only "AUTOINCREMENT" and "PRIMARY KEY" are added if appropriate.
      *
+     * @param array $columnDef
      * @return string
      */
     public function getCustomTypeDeclarationSQL(array $columnDef)
@@ -1789,6 +1799,7 @@ abstract class AbstractPlatform
      * Obtain DBMS specific SQL code portion needed to set an index
      * declaration to be used in statements like CREATE TABLE.
      *
+     * @param array $fields
      * @return string
      */
     public function getIndexFieldDeclarationListSQL(array $fields)
@@ -1916,9 +1927,9 @@ abstract class AbstractPlatform
      * returns given referential action in uppercase if valid, otherwise throws
      * an exception
      *
-     * @throws Doctrine_Exception_Exception     if unknown referential action given
+     * @throws \InvalidArgumentException if unknown referential action given
      * @param string $action    foreign key referential action
-     * @param string            foreign key referential action in uppercase
+     * @return string
      */
     public function getForeignKeyReferentialActionSQL($action)
     {
@@ -2035,6 +2046,7 @@ abstract class AbstractPlatform
      * The default conversion in this implementation converts to integers (false => 0, true => 1).
      *
      * @param mixed $item
+     * @return mixed
      */
     public function convertBooleans($item)
     {
@@ -2572,7 +2584,7 @@ abstract class AbstractPlatform
      * Makes any fixes to a name of a schema element (table, sequence, ...) that are required
      * by restrictions of the platform, like a maximum length.
      *
-     * @param string $schemaName
+     * @param string $schemaElementName
      * @return string
      */
     public function fixSchemaElementName($schemaElementName)

lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php

@@ -66,7 +66,7 @@ class CompositeExpression implements \Countable
     /**
      * Adds multiple parts to composite expression.
      *
-     * @param array $args
+     * @param array $parts
      *
      * @return CompositeExpression
      */

lib/Doctrine/DBAL/Query/Expression/ExpressionBuilder.php

@@ -94,7 +94,7 @@ class ExpressionBuilder
      * Creates a comparison expression.
      *
      * @param mixed $x Left expression
-     * @param string $operator One of the ExpressionBuikder::* constants.
+     * @param string $operator One of the ExpressionBuilder::* constants.
      * @param mixed $y Right expression
      * @return string
      */

lib/Doctrine/DBAL/Query/QueryBuilder.php

@@ -134,7 +134,7 @@ class QueryBuilder
      * For more complex expression construction, consider storing the expression
      * builder object in a local variable.
      *
-     * @return \Doctrine\DBAL\Query\ExpressionBuilder
+     * @return \Doctrine\DBAL\Query\Expression\ExpressionBuilder
      */
     public function expr()
     {
@@ -271,6 +271,7 @@ class QueryBuilder
      * </code>
      *
      * @param array $params The query parameters to set.
+     * @param array $types  The query parameters types to set.
      * @return QueryBuilder This QueryBuilder instance.
      */
     public function setParameters(array $params, array $types = array())
@@ -358,7 +359,7 @@ class QueryBuilder
      *
      * @param string  $sqlPartName
      * @param string  $sqlPart
-     * @param string $append
+     * @param boolean $append
      * @return \Doctrine\DBAL\Query\QueryBuilder This QueryBuilder instance.
      */
     public function add($sqlPartName, $sqlPart, $append = false)
@@ -940,11 +941,6 @@ class QueryBuilder
         return $this;
     }
 
-    /**
-     * Converts this instance into a SELECT string in SQL.
-     *
-     * @return string
-     */
     private function getSQLForSelect()
     {
         $query = 'SELECT ' . implode(', ', $this->sqlParts['select']) . ' FROM ';

lib/Doctrine/DBAL/SQLParserUtils.php

@@ -82,6 +82,7 @@ class SQLParserUtils
      * @param string $query
      * @param array $params
      * @param array $types
+     * @return array
      */
     static public function expandListParameters($query, $params, $types)
     {

lib/Doctrine/DBAL/Schema/AbstractSchemaManager.php

@@ -68,7 +68,7 @@ abstract class AbstractSchemaManager
     /**
      * Return associated platform.
      *
-     * @return \Doctrine\DBAL\Platform\AbstractPlatform
+     * @return \Doctrine\DBAL\Platforms\AbstractPlatform
      */
     public function getDatabasePlatform()
     {
@@ -497,7 +497,7 @@ abstract class AbstractSchemaManager
      * Drop and create a new sequence
      *
      * @param Sequence $sequence
-     * @throws Doctrine\DBAL\ConnectionException     if something fails at database level
+     * @throws \Doctrine\DBAL\ConnectionException     if something fails at database level
      */
     public function dropAndCreateSequence(Sequence $sequence)
     {

lib/Doctrine/DBAL/Statement.php

@@ -43,15 +43,15 @@ class Statement implements \IteratorAggregate, DriverStatement
      */
     protected $params = array();
     /**
-     * @var Doctrine\DBAL\Driver\Statement The underlying driver statement.
+     * @var \Doctrine\DBAL\Driver\Statement The underlying driver statement.
      */
     protected $stmt;
     /**
-     * @var Doctrine\DBAL\Platforms\AbstractPlatform The underlying database platform.
+     * @var \Doctrine\DBAL\Platforms\AbstractPlatform The underlying database platform.
      */
     protected $platform;
     /**
-     * @var Doctrine\DBAL\Connection The connection this statement is bound to and executed on.
+     * @var \Doctrine\DBAL\Connection The connection this statement is bound to and executed on.
      */
     protected $conn;
 
@@ -77,8 +77,8 @@ class Statement implements \IteratorAggregate, DriverStatement
      * type and the value undergoes the conversion routines of the mapping type before
      * being bound.
      *
-     * @param $name The name or position of the parameter.
-     * @param $value The value of the parameter.
+     * @param string $name The name or position of the parameter.
+     * @param mixed $value The value of the parameter.
      * @param mixed $type Either a PDO binding type or a DBAL mapping type name or instance.
      * @return boolean TRUE on success, FALSE on failure.
      */
@@ -107,7 +107,7 @@ class Statement implements \IteratorAggregate, DriverStatement
      * Binding a parameter by reference does not support DBAL mapping types.
      *
      * @param string $name The name or position of the parameter.
-     * @param mixed $value The reference to the variable to bind
+     * @param mixed $var The reference to the variable to bind
      * @param integer $type The PDO binding type.
      * @return boolean TRUE on success, FALSE on failure.
      */
@@ -119,6 +119,7 @@ class Statement implements \IteratorAggregate, DriverStatement
     /**
      * Executes the statement with the currently bound parameters.
      *
+     * @param array $params
      * @return boolean TRUE on success, FALSE on failure.
      */
     public function execute($params = null)