Skip to content

Loading…

PHPDoc blocks improvments + 1 CS Fix #125

Merged
merged 4 commits into from

3 participants

@adrienbrault

Hey guys,

I started to fix a class type inside Connection and then i went ahead to see what i could also improve!

Adrien

@stof stof commented on an outdated diff
lib/Doctrine/DBAL/Connection.php
@@ -419,9 +419,9 @@ public function isTransactionActive()
/**
* 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.
- * @return integer The number of affected rows.
+ * @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 int The number of affected rows.
@stof Doctrine member
stof added a note

you should keep integer which is used everywhere IMO.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@stof stof commented on an outdated diff
lib/Doctrine/DBAL/Platforms/AbstractPlatform.php
@@ -633,9 +636,9 @@ public function getLowerExpression($str)
/**
* 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 $str literal string
+ * @param string $substr literal string to find
+ * @param boolean $startPos position to start at, beginning of string by default
@stof Doctrine member
stof added a note

this is wrong. $startPos is either an integer or false when not used

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@stof stof commented on an outdated diff
lib/Doctrine/DBAL/Platforms/AbstractPlatform.php
@@ -1918,7 +1929,7 @@ public function getAdvancedForeignKeyOptionsSQL(ForeignKeyConstraint $foreignKey
*
* @throws Doctrine_Exception_Exception if unknown referential action given
@stof Doctrine member
stof added a note

the exception name is wrong too

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@adrienbrault

Thanks for the fast feedback. Referenced the PR from my commits, not sure if this is a good idea though.

@jwage
Doctrine member

:+1:

@jwage jwage merged commit 394f7e9 into doctrine:master
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
View
20 lib/Doctrine/DBAL/Cache/ResultCacheStatement.php
@@ -151,23 +151,6 @@ public function getIterator()
* 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 @@ public function fetch($fetchStyle = PDO::FETCH_BOTH)
* 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)
View
32 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 @@ public function getDatabasePlatform()
/**
* Gets the ExpressionBuilder for the connection.
*
- * @return \Doctrine\DBAL\Query\ExpressionBuilder
+ * @return \Doctrine\DBAL\Query\Expression\ExpressionBuilder
*/
public function getExpressionBuilder()
{
@@ -419,8 +419,8 @@ public function isTransactionActive()
/**
* 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 @@ public function close()
* Sets the transaction isolation level.
*
* @param integer $level The level to set.
+ * @return integer
*/
public function setTransactionIsolation($level)
{
@@ -475,7 +476,8 @@ public function getTransactionIsolation()
/**
* 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 @@ public function update($tableName, array $data, array $identifier, array $types
/**
* 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 @@ public function transactional(Closure $func)
/**
* Set if nested transactions should use savepoints
*
- * @param boolean
+ * @param boolean $nestTransactionsWithSavepoints
* @return void
*/
public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
@@ -1151,7 +1153,7 @@ public function convertToPHPValue($value, $type)
* 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 @@ private function getBindingInfo($value, $type)
/**
* Create a new instance of a SQL query builder.
*
- * @return Query\QueryBuilder
+ * @return \Doctrine\DBAL\Query\QueryBuilder
*/
public function createQueryBuilder()
{
View
2 lib/Doctrine/DBAL/Driver.php
@@ -51,7 +51,7 @@ public function getDatabasePlatform();
* 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);
View
20 lib/Doctrine/DBAL/Driver/ResultStatement.php
@@ -62,23 +62,6 @@ public function setFetchMode($fetchStyle);
* 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 @@ function fetch($fetchStyle = PDO::FETCH_BOTH);
* 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);
View
2 lib/Doctrine/DBAL/Driver/Statement.php
@@ -61,7 +61,7 @@ function bindValue($param, $value, $type = null);
* 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
*
View
50 lib/Doctrine/DBAL/Platforms/AbstractPlatform.php
@@ -226,6 +226,8 @@ protected function getVarcharTypeDeclarationSQLSnippet($length, $fixed)
/**
* Gets the SQL Snippet used to declare a BLOB column type.
+ *
+ * @param array $field
*/
abstract public function getBlobTypeDeclarationSQL(array $field);
@@ -269,11 +271,11 @@ public function getDoctrineTypeMapping($dbType)
}
$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 @@ protected function initializeCommentedDoctrineTypes()
* 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 @@ public function getSumExpression($column)
*
* Note: Not SQL92, but common functionality
*
+ * @param string $column
* @return string
*/
public function getMd5Expression($column)
@@ -512,8 +515,7 @@ public function getMd5Expression($column)
/**
* 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 @@ public function getSqrtExpression($column)
/**
* 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 @@ public function getLowerExpression($str)
/**
* 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 $str literal string
+ * @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 @@ public function getConcatExpression()
* ->where($e->eq('id', $e->not('null'));
* </code>
*
+ * @param string $expression
* @return string a logical expression
*/
public function getNotExpression($expression)
@@ -715,8 +719,8 @@ public function getNotExpression($expression)
* must contain a logical expression or an array with logical expressions.
* 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 $column the value that should be matched against
+ * @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 @@ public function getAlterSequenceSQL(\Doctrine\DBAL\Schema\Sequence $sequence)
/**
* 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 @@ public function getCreatePrimaryKeySQL(Index $index, $table)
/**
* 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 @@ public function quoteIdentifier($str)
}
/**
- * 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 @@ public function getAlterTableSQL(TableDiff $diff)
* @param Column $column
* @param TableDiff $diff
* @param array $columnSql
+ * @return boolean
*/
protected function onSchemaAlterTableAddColumn(Column $column, TableDiff $diff, &$columnSql)
{
@@ -1403,6 +1408,7 @@ protected function onSchemaAlterTableAddColumn(Column $column, TableDiff $diff,
* @param Column $column
* @param TableDiff $diff
* @param array $columnSql
+ * @return boolean
*/
protected function onSchemaAlterTableRemoveColumn(Column $column, TableDiff $diff, &$columnSql)
{
@@ -1426,6 +1432,7 @@ protected function onSchemaAlterTableRemoveColumn(Column $column, TableDiff $dif
* @param ColumnDiff $columnDiff
* @param TableDiff $diff
* @param array $columnSql
+ * @return boolean
*/
protected function onSchemaAlterTableChangeColumn(ColumnDiff $columnDiff, TableDiff $diff, &$columnSql)
{
@@ -1450,6 +1457,7 @@ protected function onSchemaAlterTableChangeColumn(ColumnDiff $columnDiff, TableD
* @param Column $column
* @param TableDiff $diff
* @param array $columnSql
+ * @return boolean
*/
protected function onSchemaAlterTableRenameColumn($oldColumnName, Column $column, TableDiff $diff, &$columnSql)
{
@@ -1470,7 +1478,8 @@ protected function onSchemaAlterTableRenameColumn($oldColumnName, Column $column
}
/**
* @param TableDiff $diff
- * @param array $columnSql
+ * @param array $qql
+ * @return boolean
*/
protected function onSchemaAlterTable(TableDiff $diff, &$sql)
{
@@ -1777,6 +1786,7 @@ public function getIndexDeclarationSQL($name, Index $index)
* 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 @@ public function getCustomTypeDeclarationSQL(array $columnDef)
* 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 @@ public function getAdvancedForeignKeyOptionsSQL(ForeignKeyConstraint $foreignKey
* 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 @@ public function prefersIdentityColumns()
* 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 @@ public function getSQLResultCasing($column)
* 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)
View
2 lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php
@@ -66,7 +66,7 @@ public function __construct($type, array $parts = array())
/**
* Adds multiple parts to composite expression.
*
- * @param array $args
+ * @param array $parts
*
* @return CompositeExpression
*/
View
2 lib/Doctrine/DBAL/Query/Expression/ExpressionBuilder.php
@@ -94,7 +94,7 @@ public function orX($x = null)
* 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
*/
View
14 lib/Doctrine/DBAL/Query/QueryBuilder.php
@@ -134,7 +134,7 @@ public function __construct(Connection $connection)
* 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 @@ public function setParameter($key, $value, $type = null)
* </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())
@@ -356,9 +357,9 @@ public function getMaxResults()
* The available parts are: 'select', 'from', 'set', 'where',
* 'groupBy', 'having' and 'orderBy'.
*
- * @param string $sqlPartName
- * @param string $sqlPart
- * @param string $append
+ * @param string $sqlPartName
+ * @param string $sqlPart
+ * @param boolean $append
* @return \Doctrine\DBAL\Query\QueryBuilder This QueryBuilder instance.
*/
public function add($sqlPartName, $sqlPart, $append = false)
@@ -940,11 +941,6 @@ public function resetQueryPart($queryPartName)
return $this;
}
- /**
- * Converts this instance into a SELECT string in SQL.
- *
- * @return string
- */
private function getSQLForSelect()
{
$query = 'SELECT ' . implode(', ', $this->sqlParts['select']) . ' FROM ';
View
1 lib/Doctrine/DBAL/SQLParserUtils.php
@@ -82,6 +82,7 @@ static public function getPlaceholderPositions($statement, $isPositional = true)
* @param string $query
* @param array $params
* @param array $types
+ * @return array
*/
static public function expandListParameters($query, $params, $types)
{
View
4 lib/Doctrine/DBAL/Schema/AbstractSchemaManager.php
@@ -68,7 +68,7 @@ public function __construct(\Doctrine\DBAL\Connection $conn)
/**
* Return associated platform.
*
- * @return \Doctrine\DBAL\Platform\AbstractPlatform
+ * @return \Doctrine\DBAL\Platforms\AbstractPlatform
*/
public function getDatabasePlatform()
{
@@ -497,7 +497,7 @@ public function dropAndCreateForeignKey(ForeignKeyConstraint $foreignKey, $table
* 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)
{
View
13 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 @@ public function __construct($sql, Connection $conn)
* 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 @@ public function bindValue($name, $value, $type = null)
* 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 @@ public function bindParam($name, &$var, $type = PDO::PARAM_STR)
/**
* Executes the statement with the currently bound parameters.
*
+ * @param array $params
* @return boolean TRUE on success, FALSE on failure.
*/
public function execute($params = null)
Something went wrong with that request. Please try again.