phpDoc: added $var name to @param, improved typehints

dg · dg · commit 277296d13cb3 · 2018-03-23T15:48:02.000+01:00
diff --git a/src/Database/Connection.php b/src/Database/Connection.php
@@ -110,24 +110,17 @@ public function getSupplementalDriver(): ISupplementalDriver
 	}
 
 
-	/**
-	 * @param  string  sequence object
-	 */
-	public function getInsertId(string $name = null): string
+	public function getInsertId(string $sequence = null): string
 	{
 		try {
-			$res = $this->getPdo()->lastInsertId($name);
+			$res = $this->getPdo()->lastInsertId($sequence);
 			return $res === false ? '0' : $res;
 		} catch (PDOException $e) {
 			throw $this->driver->convertException($e);
 		}
 	}
 
 
-	/**
-	 * @param  string  string to be quoted
-	 * @param  int     data type hint
-	 */
 	public function quote(string $string, int $type = PDO::PARAM_STR): string
 	{
 		try {
@@ -180,7 +173,7 @@ public function queryArgs(string $sql, array $params): ResultSet
 
 
 	/**
-	 * @return [string, array]
+	 * @return array  [string, array]
 	 */
 	public function preprocess($sql, ...$params): array
 	{
diff --git a/src/Database/Context.php b/src/Database/Context.php
@@ -60,12 +60,9 @@ public function rollBack(): void
 	}
 
 
-	/**
-	 * @param  string  sequence object
-	 */
-	public function getInsertId(string $name = null): string
+	public function getInsertId(string $sequence = null): string
 	{
-		return $this->connection->getInsertId($name);
+		return $this->connection->getInsertId($sequence);
 	}
 
 
diff --git a/src/Database/Conventions/StaticConventions.php b/src/Database/Conventions/StaticConventions.php
@@ -32,9 +32,9 @@ class StaticConventions implements IConventions
 
 	/**
 	 * Create static conventional structure.
-	 * @param  string %s stands for table name
-	 * @param  string %1$s stands for key used after ->, %2$s for table name
-	 * @param  string %1$s stands for key used after ->, %2$s for table name
+	 * @param  string  $primary  %s stands for table name
+	 * @param  string  $foreign  %1$s stands for key used after ->, %2$s for table name
+	 * @param  string  $table  %1$s stands for key used after ->, %2$s for table name
 	 */
 	public function __construct(string $primary = 'id', string $foreign = '%s_id', string $table = '%s')
 	{
diff --git a/src/Database/Helpers.php b/src/Database/Helpers.php
@@ -177,7 +177,7 @@ public static function detectType(string $type): string
 
 	/**
 	 * Import SQL dump from file - extremely fast.
-	 * @param  $onProgress  function (int $count, ?float $percent): void
+	 * @param  callable  $onProgress  function (int $count, ?float $percent): void
 	 * @return int  count of commands
 	 */
 	public static function loadFromFile(Connection $connection, string $file, callable $onProgress = null): int
diff --git a/src/Database/IConventions.php b/src/Database/IConventions.php
@@ -26,8 +26,6 @@ function getPrimary(string $table);
 	 * Example:
 	 *     (author, book) returns array(book, author_id)
 	 *
-	 * @param  string  source table
-	 * @param  string  referencing key
 	 * @return array|null   array(referenced table, referenced column)
 	 * @throws AmbiguousReferenceKeyException
 	 */
@@ -39,8 +37,6 @@ function getHasManyReference(string $table, string $key): ?array;
 	 *     (book, author)      returns array(author, author_id)
 	 *     (book, translator)  returns array(author, translator_id)
 	 *
-	 * @param  string  source table
-	 * @param  string  referencing key
 	 * @return array|null   array(referenced table, referencing column)
 	 */
 	function getBelongsToReference(string $table, string $key): ?array;
diff --git a/src/Database/IRowContainer.php b/src/Database/IRowContainer.php
@@ -29,8 +29,8 @@ function fetchField();
 
 	/**
 	 * Fetches all rows as associative array.
-	 * @param  string|int column name used for an array key or null for numeric index
-	 * @param  string|int column name used for an array value or null for the whole row
+	 * @param  string|int  $key  column name used for an array key or null for numeric index
+	 * @param  string|int  $value  column name used for an array value or null for the whole row
 	 */
 	function fetchPairs($key = null, $value = null): array;
 
@@ -42,7 +42,7 @@ function fetchAll(): array;
 
 	/**
 	 * Fetches all rows and returns associative tree.
-	 * @param  string  associative descriptor
+	 * @param  string  $path  associative descriptor
 	 */
 	function fetchAssoc(string $path): array;
 }
diff --git a/src/Database/ISupplementalDriver.php b/src/Database/ISupplementalDriver.php
@@ -55,7 +55,7 @@ function formatLike(string $value, int $pos): string;
 
 	/**
 	 * Injects LIMIT/OFFSET to the SQL query.
-	 * @param  string  SQL query that will be modified.
+	 * @param  string  $sql query that will be modified.
 	 */
 	function applyLimit(string &$sql, ?int $limit, ?int $offset): void;
 
@@ -91,7 +91,7 @@ function getColumnTypes(\PDOStatement $statement): array;
 
 	/**
 	 * Cheks if driver supports specific property
-	 * @param  string self::SUPPORT_* property
+	 * @param  string  $item  self::SUPPORT_* property
 	 */
 	function isSupported(string $item): bool;
 }
diff --git a/src/Database/Row.php b/src/Database/Row.php
@@ -26,7 +26,7 @@ public function __get($key)
 
 	/**
 	 * Returns a item.
-	 * @param  mixed  key or index
+	 * @param  string|int  $key  key or index
 	 * @return mixed
 	 */
 	public function offsetGet($key)
@@ -44,7 +44,7 @@ public function offsetGet($key)
 
 	/**
 	 * Checks if $key exists.
-	 * @param  mixed  key or index
+	 * @param  string|int  $key  key or index
 	 */
 	public function offsetExists($key): bool
 	{
diff --git a/src/Database/Table/ActiveRow.php b/src/Database/Table/ActiveRow.php
@@ -214,8 +214,8 @@ public function getIterator(): \Iterator
 
 	/**
 	 * Stores value in column.
-	 * @param  string
-	 * @param  mixed
+	 * @param  string  $column
+	 * @param  mixed  $value
 	 */
 	public function offsetSet($column, $value): void
 	{
@@ -225,7 +225,7 @@ public function offsetSet($column, $value): void
 
 	/**
 	 * Returns value of column.
-	 * @param  string
+	 * @param  string  $column
 	 * @return mixed
 	 */
 	public function offsetGet($column)
@@ -236,7 +236,7 @@ public function offsetGet($column)
 
 	/**
 	 * Tests if column exists.
-	 * @param  string
+	 * @param  string  $column
 	 */
 	public function offsetExists($column): bool
 	{
@@ -246,7 +246,7 @@ public function offsetExists($column): bool
 
 	/**
 	 * Removes column from data.
-	 * @param  string
+	 * @param  string  $column
 	 */
 	public function offsetUnset($column): void
 	{
diff --git a/src/Database/Table/ColumnAccessCache.php b/src/Database/Table/ColumnAccessCache.php
@@ -177,9 +177,6 @@ public function &loadFromRefCache(&$referencing): string
 	}
 
 
-	/**
-	 * @param Selection
-	 */
 	public function setObserveCache(Selection $observeCache): void
 	{
 		$this->observeCache = $observeCache;
diff --git a/src/Database/Table/GroupedSelection.php b/src/Database/Table/GroupedSelection.php
@@ -35,8 +35,6 @@ class GroupedSelection extends Selection
 
 	/**
 	 * Creates filtered and grouped table representation.
-	 * @param  string $tableName  database table name
-	 * @param  string $column  joining column
 	 */
 	public function __construct(Context $context, IConventions $conventions, string $tableName, string $column, Selection $refTable, Nette\Caching\IStorage $cacheStorage = null)
 	{
@@ -49,7 +47,7 @@ public function __construct(Context $context, IConventions $conventions, string
 	/**
 	 * Sets active group.
 	 * @internal
-	 * @param  int  primary key of grouped rows
+	 * @param  int  $active  primary key of grouped rows
 	 * @return static
 	 */
 	public function setActive(int $active)
diff --git a/src/Database/Table/Selection.php b/src/Database/Table/Selection.php
@@ -67,7 +67,6 @@ class Selection implements \Iterator, IRowContainer, \ArrayAccess, \Countable
 
 	/**
 	 * Creates filtered table representation.
-	 * @param  string $tableName  table name
 	 */
 	public function __construct(Context $context, IConventions $conventions, string $tableName, Nette\Caching\IStorage $cacheStorage = null)
 	{
@@ -183,7 +182,7 @@ public function getConnection(): Nette\Database\Connection
 
 	/**
 	 * Returns row specified by primary key.
-	 * @param  mixed primary key
+	 * @param  mixed  $key  primary key
 	 */
 	public function get($key): ?ActiveRow
 	{
@@ -207,7 +206,6 @@ public function fetch(): ?Nette\Database\IRow
 
 	/**
 	 * Fetches single field.
-	 * @param  string|null
 	 * @return mixed
 	 * @deprecated
 	 */
@@ -259,7 +257,7 @@ public function fetchAssoc(string $path): array
 
 	/**
 	 * Adds select clause, more calls appends to the end.
-	 * @param  string|string[] for example "column, MD5(column) AS column_md5"
+	 * @param  string|string[]  $columns  for example "column, MD5(column) AS column_md5"
 	 * @return static
 	 */
 	public function select($columns, ...$params)
@@ -272,7 +270,7 @@ public function select($columns, ...$params)
 
 	/**
 	 * Adds condition for primary key.
-	 * @param  mixed
+	 * @param  mixed  $key
 	 * @return static
 	 */
 	public function wherePrimary($key)
@@ -297,8 +295,7 @@ public function wherePrimary($key)
 
 	/**
 	 * Adds where condition, more calls appends with AND.
-	 * @param  string|string[] condition possibly containing ?
-	 * @param  mixed
+	 * @param  string|string[]  $condition  possibly containing ?
 	 * @return static
 	 */
 	public function where($condition, ...$params)
@@ -310,9 +307,8 @@ public function where($condition, ...$params)
 
 	/**
 	 * Adds ON condition when joining specified table, more calls appends with AND.
-	 * @param  string table chain or table alias for which you need additional left join condition
-	 * @param  string condition possibly containing ?
-	 * @param  mixed
+	 * @param  string  $tableChain  table chain or table alias for which you need additional left join condition
+	 * @param  string  $condition  possibly containing ?
 	 * @return static
 	 */
 	public function joinWhere(string $tableChain, string $condition, ...$params)
@@ -324,7 +320,7 @@ public function joinWhere(string $tableChain, string $condition, ...$params)
 
 	/**
 	 * Adds condition, more calls appends with AND.
-	 * @param  string|string[] condition possibly containing ?
+	 * @param  string|string[]  $condition  possibly containing ?
 	 */
 	protected function condition($condition, array $params, $tableChain = null): void
 	{
@@ -348,7 +344,7 @@ protected function condition($condition, array $params, $tableChain = null): voi
 	/**
 	 * Adds where condition using the OR operator between parameters.
 	 * More calls appends with AND.
-	 * @param  array ['column1' => 1, 'column2 > ?' => 2, 'full condition']
+	 * @param  array  $parameters ['column1' => 1, 'column2 > ?' => 2, 'full condition']
 	 * @return static
 	 * @throws \Nette\InvalidArgumentException
 	 */
@@ -381,7 +377,7 @@ public function whereOr(array $parameters)
 
 	/**
 	 * Adds order clause, more calls appends to the end.
-	 * @param  string for example 'column1, column2 DESC'
+	 * @param  string  $columns  for example 'column1, column2 DESC'
 	 * @return static
 	 */
 	public function order(string $columns, ...$params)
@@ -460,7 +456,7 @@ public function alias(string $tableChain, string $alias)
 
 	/**
 	 * Executes aggregation function.
-	 * @param  string select call in "FUNCTION(column)" format
+	 * @param  string  $function  select call in "FUNCTION(column)" format
 	 * @return mixed
 	 */
 	public function aggregation(string $function)
@@ -476,7 +472,7 @@ public function aggregation(string $function)
 
 	/**
 	 * Counts number of rows.
-	 * @param  string  if it is not provided returns count of result rows, otherwise runs new sql counting query
+	 * @param  string  $column  if it is not provided returns count of result rows, otherwise runs new sql counting query
 	 */
 	public function count(string $column = null): int
 	{
@@ -646,7 +642,6 @@ protected function linkRefCache(): void
 
 	/**
 	 * @internal
-	 * @param  string column name
 	 * @return bool if selection requeried for more columns.
 	 */
 	public function accessColumn(string $key, bool $selectColumn = true): bool
@@ -738,7 +733,7 @@ protected function refreshData(): void
 
 	/**
 	 * Inserts row in a table.
-	 * @param  array|\Traversable|Selection array($column => $value)|\Traversable|Selection for INSERT ... SELECT
+	 * @param  array|\Traversable|Selection  $data  array($column => $value)|\Traversable|Selection for INSERT ... SELECT
 	 * @return ActiveRow|int|bool Returns IRow or number of affected rows for Selection or table without primary key
 	 */
 	public function insert($data)
@@ -901,7 +896,7 @@ public function getReferencedTable(ActiveRow $row, ?string $table, string $colum
 
 	/**
 	 * Returns referencing rows.
-	 * @param  int $active primary key
+	 * @param  int  $active  primary key
 	 */
 	public function getReferencingTable(string $table, string $column = null, int $active = null): ?GroupedSelection
 	{
@@ -977,8 +972,8 @@ public function valid(): bool
 
 	/**
 	 * Mimic row.
-	 * @param  string row ID
-	 * @param  IRow
+	 * @param  string  $key
+	 * @param  IRow  $value
 	 */
 	public function offsetSet($key, $value): void
 	{
@@ -989,7 +984,7 @@ public function offsetSet($key, $value): void
 
 	/**
 	 * Returns specified row.
-	 * @param  string row ID
+	 * @param  string  $key
 	 */
 	public function offsetGet($key): ?ActiveRow
 	{
@@ -1000,7 +995,7 @@ public function offsetGet($key): ?ActiveRow
 
 	/**
 	 * Tests if row exists.
-	 * @param  string row ID
+	 * @param  string  $key
 	 */
 	public function offsetExists($key): bool
 	{
@@ -1011,7 +1006,7 @@ public function offsetExists($key): bool
 
 	/**
 	 * Removes row from result set.
-	 * @param  string row ID
+	 * @param  string  $key
 	 */
 	public function offsetUnset($key): void
 	{
diff --git a/src/Database/Table/SqlBuilder.php b/src/Database/Table/SqlBuilder.php
@@ -178,7 +178,7 @@ public function getSelectQueryHash(array $columns = null): string
 
 	/**
 	 * Returns SQL query.
-	 * @param  string[] list of columns
+	 * @param  string[]  $columns
 	 */
 	public function buildSelectQuery(array $columns = null): string
 	{

Original file line number	Diff line number	Diff line change
`@@ -110,24 +110,17 @@ public function getSupplementalDriver(): ISupplementalDriver`
`110`	`110`	`}`
`111`	`111`
`112`	`112`
`113`		`- /**`
`114`		`- * @param string sequence object`
`115`		`- */`
`116`		`- public function getInsertId(string $name = null): string`
	`113`	`+ public function getInsertId(string $sequence = null): string`
`117`	`114`	`{`
`118`	`115`	`try {`
`119`		`- $res = $this->getPdo()->lastInsertId($name);`
	`116`	`+ $res = $this->getPdo()->lastInsertId($sequence);`
`120`	`117`	`return $res === false ? '0' : $res;`
`121`	`118`	`} catch (PDOException $e) {`
`122`	`119`	`throw $this->driver->convertException($e);`
`123`	`120`	`}`
`124`	`121`	`}`
`125`	`122`
`126`	`123`
`127`		`- /**`
`128`		`- * @param string string to be quoted`
`129`		`- * @param int data type hint`
`130`		`- */`
`131`	`124`	`public function quote(string $string, int $type = PDO::PARAM_STR): string`
`132`	`125`	`{`
`133`	`126`	`try {`
`@@ -180,7 +173,7 @@ public function queryArgs(string $sql, array $params): ResultSet`
`180`	`173`
`181`	`174`
`182`	`175`	`/**`
`183`		`- * @return [string, array]`
	`176`	`+ * @return array [string, array]`
`184`	`177`	`*/`
`185`	`178`	`public function preprocess($sql, ...$params): array`
`186`	`179`	`{`
Original file line number	Diff line number	Diff line change
`@@ -60,12 +60,9 @@ public function rollBack(): void`
`60`	`60`	`}`
`61`	`61`
`62`	`62`
`63`		`- /**`
`64`		`- * @param string sequence object`
`65`		`- */`
`66`		`- public function getInsertId(string $name = null): string`
	`63`	`+ public function getInsertId(string $sequence = null): string`
`67`	`64`	`{`
`68`		`- return $this->connection->getInsertId($name);`
	`65`	`+ return $this->connection->getInsertId($sequence);`
`69`	`66`	`}`
`70`	`67`
`71`	`68`
Original file line number	Diff line number	Diff line change
`@@ -177,9 +177,6 @@ public function &loadFromRefCache(&$referencing): string`
`177`	`177`	`}`
`178`	`178`
`179`	`179`
`180`		`- /**`
`181`		`- * @param Selection`
`182`		`- */`
`183`	`180`	`public function setObserveCache(Selection $observeCache): void`
`184`	`181`	`{`
`185`	`182`	`$this->observeCache = $observeCache;`