Merge pull request #31 from mvorisek/fix_return_phpdoc_for_chaining

Improve return `$this` phpdoc for chaining
DataTables · Dec 7, 2023 · 2bfe076 · 2bfe076
2 parents ee74641 + 4bf9e88
commit 2bfe076
Show file tree

Hide file tree

Showing 15 changed files with 146 additions and 247 deletions.
diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php
@@ -4,7 +4,7 @@
 	->in(array(__DIR__))
 	->ignoreDotFiles(false)
 	->ignoreVCS(true)
-	->exclude(array('vendor'));
+	->exclude(array('vendor', 'HtmLawed'));
 
 $config = new PhpCsFixer\Config();
 
@@ -66,6 +66,7 @@
 		'single_line_comment_style' => false,
 		'phpdoc_annotation_without_dot' => false,
 		'declare_strict_types' => false,
+		'static_lambda' => false, // needs PHP 5.4+
 		'strict_comparison' => false,
 		'strict_param' => false, // TODO
 		'final_internal_class' => false,

diff --git a/Database.php b/Database.php
@@ -109,7 +109,7 @@ public function any($table, $where = null)
 	 *
 	 * Use with {@see Database->transaction()} and {@see Database->rollback()}.
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function commit()
 	{
@@ -146,8 +146,7 @@ public function count($table, $field = 'id', $where = null)
 	 *
 	 * @param bool $set Debug mode state. If not given, then used as a getter.
 	 *
-	 * @return bool|self Debug mode state if no parameter is given, or
-	 *                   self if used as a setter.
+	 * @return ($set is null ? bool : $this) Debug mode state if no parameter is given.
 	 */
 	public function debug($set = null)
 	{
@@ -312,7 +311,7 @@ public function resource()
 	 *
 	 * Use with {@see Database->transaction()} and {@see Database->commit()}.
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function rollback()
 	{
@@ -410,7 +409,7 @@ public function sql($sql)
 	 *
 	 * Use with {@see Database->commit()} and {@see Database->rollback()}.
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function transaction()
 	{
@@ -457,8 +456,8 @@ public function update($table, $set = null, $where = null)
 	/**
 	 * Get debug query information.
 	 *
-	 * @return Database Information about the queries used. When this method is
-	 *                  called it will reset the query cache.
+	 * @return $this Information about the queries used. When this method is
+	 *               called it will reset the query cache.
 	 *
 	 * @internal
 	 */

diff --git a/Database/Driver/PostgresQuery.php b/Database/Driver/PostgresQuery.php
@@ -93,12 +93,12 @@ protected function _prepare($sql)
 
 			// Get the pkey field name
 			$pkRes = $resource->prepare(
-				"SELECT a.attname
+				'SELECT a.attname
 				FROM   pg_index i
 				JOIN   pg_attribute a ON a.attrelid = i.indrelid
 									 AND a.attnum = ANY(i.indkey)
 				WHERE  i.indrelid = (:tableName)::regclass
-				AND    i.indisprimary"
+				AND    i.indisprimary'
 			);
 			$pkRes->bindValue('tableName', $table[0]);
 			$pkRes->execute();

diff --git a/Database/Query.php b/Database/Query.php
@@ -196,7 +196,7 @@ public static function commit($dbh)
 	 * @param string       $host Host name
 	 * @param string       $db   Database name
 	 *
-	 * @return Query
+	 * @return \PDO
 	 */
 	public static function connect($user, $pass = '', $host = '', $port = '', $db = '', $dsn = '')
 	{
@@ -262,7 +262,7 @@ public static function dsnPostfix($dsn)
 	 * @param mixed  $type  Data type. See the PHP PDO documentation:
 	 *                      http://php.net/manual/en/pdo.constants.php
 	 *
-	 * @return Query
+	 * @return $this
 	 */
 	public function bind($name, $value, $type = null)
 	{
@@ -291,7 +291,7 @@ public function database()
 	 *
 	 * @param bool $dis Optional
 	 *
-	 * @return Query
+	 * @return $this
 	 */
 	public function distinct($dis)
 	{
@@ -334,7 +334,7 @@ public function exec($sql = null)
 	 * @param string|string[] ...$get Fields to get - can be specified as
 	 *                                individual fields or an array of fields.
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function get($get)
 	{
@@ -374,7 +374,7 @@ public function get($get)
 	 * @param string $condition JOIN condition
 	 * @param string $type      JOIN type
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function join($table, $condition, $type = '', $bind = true)
 	{
@@ -402,6 +402,8 @@ public function join($table, $condition, $type = '', $bind = true)
 
 	/**
 	 * Add a left join, with common logic for handling binding or not.
+	 *
+	 * @return $this
 	 */
 	public function left_join($joins)
 	{
@@ -439,7 +441,7 @@ public function left_join($joins)
 	 *
 	 * @param int $lim The number of records to limit the result to.
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function limit($lim)
 	{
@@ -453,7 +455,7 @@ public function limit($lim)
 	 *
 	 * @param string $group_by The field of which the values are to be grouped
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function group_by($group_by)
 	{
@@ -468,7 +470,7 @@ public function group_by($group_by)
 	 *
 	 * @param string[] $pkey Primary keys
 	 *
-	 * @return Query|string[]
+	 * @return ($pkey is null ? string[] : $this)
 	 */
 	public function pkey($pkey = null)
 	{
@@ -488,7 +490,7 @@ public function pkey($pkey = null)
 	 *                                  individual names, an array of names, a string of comma separated
 	 *                                  names or any combination of those.
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function table($table)
 	{
@@ -518,7 +520,7 @@ public function table($table)
 	 *
 	 * @param int $off The number of records to offset the result by.
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function offset($off)
 	{
@@ -534,7 +536,7 @@ public function offset($off)
 	 *                               be specified as individual names, an array of names, a string of comma
 	 *                               separated names or any combination of those.
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function order($order)
 	{
@@ -577,7 +579,7 @@ public function order($order)
 	 *                              name and this is the field's value.
 	 * @param bool            $bind Should the value be bound or not
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function set($set, $val = null, $bind = true)
 	{
@@ -618,7 +620,7 @@ public function set($set, $val = null, $bind = true)
 	 * @param string                   $op    Condition operator: <, >, = etc
 	 * @param bool                     $bind  Escape the value (true, default) or not (false).
 	 *
-	 * @return self
+	 * @return $this
 	 *
 	 *  @example
 	 *     The following will produce
@@ -669,7 +671,7 @@ public function where($key, $value = null, $op = '=', $bind = true)
 	 * @param string                   $op    Condition operator: <, >, = etc
 	 * @param bool                     $bind  Escape the value (true, default) or not (false).
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function and_where($key, $value = null, $op = '=', $bind = true)
 	{
@@ -692,7 +694,7 @@ public function and_where($key, $value = null, $op = '=', $bind = true)
 	 * @param string                   $op    Condition operator: <, >, = etc
 	 * @param bool                     $bind  Escape the value (true, default) or not (false).
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function or_where($key, $value = null, $op = '=', $bind = true)
 	{
@@ -731,7 +733,7 @@ public function or_where($key, $value = null, $op = '=', $bind = true)
 	 * @param string        $op    Conditional operator to use to join to the
 	 *                             preceding condition. Default `AND`.
 	 *
-	 * @return self
+	 * @return $this
 	 *
 	 *  @example
 	 *     ```php
@@ -766,7 +768,7 @@ public function where_group($inOut, $op = 'AND')
 	 * @param string $operator Conditional operator to use to join to the
 	 *                         preceding condition. Default `AND`.
 	 *
-	 * @return self
+	 * @return $this
 	 */
 	public function where_in($field, $arr, $operator = 'AND')
 	{
@@ -1008,7 +1010,7 @@ protected function _build_where()
 				if ($this->_where[$i - 1]['group'] === '(') {
 					$condition .= '1=1';
 				}
-				// else nothing
+			// else nothing reindent once https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/issues/7497 is fixed
 			} elseif ($this->_where[$i - 1]['group'] === '(') {
 				// Nothing
 			} else {