Merge pull request #1235 from PHPCSStandards/feature/various-doc-fixes

jrfnl · web-flow · commit 91986ec07908 · 2025-09-11T07:45:06.000+02:00
Docs: various type fixes
diff --git a/src/Files/File.php b/src/Files/File.php
@@ -2443,8 +2443,8 @@ public function findNext(
     /**
      * Returns the position of the first non-whitespace token in a statement.
      *
-     * @param int              $start  The position to start searching from in the token stack.
-     * @param int|string|array $ignore Token types that should not be considered stop points.
+     * @param int                   $start  The position to start searching from in the token stack.
+     * @param int|string|array|null $ignore Token types that should not be considered stop points.
      *
      * @return int
      */
@@ -2634,8 +2634,8 @@ public function findStartOfStatement($start, $ignore=null)
     /**
      * Returns the position of the last non-whitespace token in a statement.
      *
-     * @param int              $start  The position to start searching from in the token stack.
-     * @param int|string|array $ignore Token types that should not be considered stop points.
+     * @param int                   $start  The position to start searching from in the token stack.
+     * @param int|string|array|null $ignore Token types that should not be considered stop points.
      *
      * @return int
      */
@@ -2756,7 +2756,7 @@ public function findEndOfStatement($start, $ignore=null)
      *                                  token stack.
      * @param bool             $exclude If true, find the token that is NOT of
      *                                  the types specified in $types.
-     * @param string           $value   The value that the token must be equal to.
+     * @param string|null      $value   The value that the token must be equal to.
      *                                  If value is omitted, tokens with any value will
      *                                  be returned.
      *
diff --git a/src/Files/FileList.php b/src/Files/FileList.php
@@ -110,8 +110,8 @@ public function __construct(Config $config, Ruleset $ruleset)
      * If a file object has already been created, it can be passed here.
      * If it is left NULL, it will be created when accessed.
      *
-     * @param string                      $path The path to the file being added.
-     * @param \PHP_CodeSniffer\Files\File $file The file being added.
+     * @param string                           $path The path to the file being added.
+     * @param \PHP_CodeSniffer\Files\File|null $file The file being added.
      *
      * @return void
      */
diff --git a/src/Fixer.php b/src/Fixer.php
@@ -222,10 +222,10 @@ public function fixFile()
     /**
      * Generates a text diff of the original file and the new content.
      *
-     * @param string  $filePath Optional file path to diff the file against.
-     *                          If not specified, the original version of the
-     *                          file will be used.
-     * @param boolean $colors   Print coloured output or not.
+     * @param string|null $filePath Optional file path to diff the file against.
+     *                              If not specified, the original version of the
+     *                              file will be used.
+     * @param boolean     $colors   Print coloured output or not.
      *
      * @return string
      *
@@ -698,10 +698,10 @@ public function revertToken($stackPtr)
     /**
      * Replace the content of a token with a part of its current content.
      *
-     * @param int $stackPtr The position of the token in the token stack.
-     * @param int $start    The first character to keep.
-     * @param int $length   The number of characters to keep. If NULL, the content of
-     *                      the token from $start to the end of the content is kept.
+     * @param int      $stackPtr The position of the token in the token stack.
+     * @param int      $start    The first character to keep.
+     * @param int|null $length   The number of characters to keep. If NULL, the content of
+     *                           the token from $start to the end of the content is kept.
      *
      * @return bool If the change was accepted.
      */
diff --git a/src/Ruleset.php b/src/Ruleset.php
@@ -1698,8 +1698,8 @@ public function setSniffProperty($sniffClass, $name, $settings)
      * Optionally takes a listener to get ignore patterns specified
      * for that sniff only.
      *
-     * @param string $listener The listener to get patterns for. If NULL, all
-     *                         patterns are returned.
+     * @param string|null $listener The listener to get patterns for. If NULL, all
+     *                              patterns are returned.
      *
      * @return array
      */
@@ -1724,8 +1724,8 @@ public function getIgnorePatterns($listener=null)
      * Optionally takes a listener to get include patterns specified
      * for that sniff only.
      *
-     * @param string $listener The listener to get patterns for. If NULL, all
-     *                         patterns are returned.
+     * @param string|null $listener The listener to get patterns for. If NULL, all
+     *                              patterns are returned.
      *
      * @return array
      */
diff --git a/src/Standards/Generic/Sniffs/Formatting/MultipleStatementAlignmentSniff.php b/src/Standards/Generic/Sniffs/Formatting/MultipleStatementAlignmentSniff.php
@@ -92,7 +92,7 @@ public function process(File $phpcsFile, $stackPtr)
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
      * @param int                         $stackPtr  The position of the current token
      *                                               in the stack passed in $tokens.
-     * @param int                         $end       The token where checking should end.
+     * @param int|null                    $end       The token where checking should end.
      *                                               If NULL, the entire file will be checked.
      *
      * @return int
diff --git a/src/Standards/Generic/Sniffs/PHP/DeprecatedFunctionsSniff.php b/src/Standards/Generic/Sniffs/PHP/DeprecatedFunctionsSniff.php
@@ -53,7 +53,7 @@ public function __construct()
      * @param int                         $stackPtr  The position of the forbidden function
      *                                               in the token array.
      * @param string                      $function  The name of the forbidden function.
-     * @param string                      $pattern   The pattern used for the match.
+     * @param string|null                 $pattern   The pattern used for the match.
      *
      * @return void
      */
diff --git a/src/Standards/Generic/Sniffs/PHP/ForbiddenFunctionsSniff.php b/src/Standards/Generic/Sniffs/PHP/ForbiddenFunctionsSniff.php
@@ -206,7 +206,7 @@ public function process(File $phpcsFile, $stackPtr)
      * @param int                         $stackPtr  The position of the forbidden function
      *                                               in the token array.
      * @param string                      $function  The name of the forbidden function.
-     * @param string                      $pattern   The pattern used for the match.
+     * @param string|null                 $pattern   The pattern used for the match.
      *
      * @return void
      */
diff --git a/src/Tokenizers/Tokenizer.php b/src/Tokenizers/Tokenizer.php
@@ -579,10 +579,10 @@ private function createPositionMap()
      * is placed into an orig_content index and the new token length is also
      * set in the length index.
      *
-     * @param array  $token    The token to replace tabs inside.
-     * @param string $prefix   The character to use to represent the start of a tab.
-     * @param string $padding  The character to use to represent the end of a tab.
-     * @param int    $tabWidth The number of spaces each tab represents.
+     * @param array    $token    The token to replace tabs inside.
+     * @param string   $prefix   The character to use to represent the start of a tab.
+     * @param string   $padding  The character to use to represent the end of a tab.
+     * @param int|null $tabWidth The number of spaces each tab represents.
      *
      * @return void
      */
diff --git a/src/Util/Cache.php b/src/Util/Cache.php
@@ -300,8 +300,8 @@ public static function save()
     /**
      * Retrieves a single entry from the cache.
      *
-     * @param string $key The key of the data to get. If NULL,
-     *                    everything in the cache is returned.
+     * @param string|null $key The key of the data to get. If NULL,
+     *                         everything in the cache is returned.
      *
      * @return mixed
      */
@@ -323,9 +323,9 @@ public static function get($key=null)
     /**
      * Retrieves a single entry from the cache.
      *
-     * @param string $key   The key of the data to set. If NULL,
-     *                      sets the entire cache.
-     * @param mixed  $value The value to set.
+     * @param string|null $key   The key of the data to set. If NULL,
+     *                           sets the entire cache.
+     * @param mixed       $value The value to set.
      *
      * @return void
      */
diff --git a/src/Util/Tokens.php b/src/Util/Tokens.php
@@ -804,8 +804,8 @@ public static function tokenName($token)
      * @param array<int|string> $tokens The token types to get the highest weighted
      *                                  type for.
      *
-     * @return int The highest weighted token.
-     *             On equal "weight", returns the first token of that particular weight.
+     * @return int|string The highest weighted token.
+     *                    On equal "weight", returns the first token of that particular weight.
      */
     public static function getHighestWeightedToken(array $tokens)
     {

Original file line number	Diff line number	Diff line change
`@@ -2443,8 +2443,8 @@ public function findNext(`
`2443`	`2443`	`/**`
`2444`	`2444`	`* Returns the position of the first non-whitespace token in a statement.`
`2445`	`2445`	`*`
`2446`		`- * @param int $start The position to start searching from in the token stack.`
`2447`		`- * @param int\|string\|array $ignore Token types that should not be considered stop points.`
	`2446`	`+ * @param int $start The position to start searching from in the token stack.`
	`2447`	`+ * @param int\|string\|array\|null $ignore Token types that should not be considered stop points.`
`2448`	`2448`	`*`
`2449`	`2449`	`* @return int`
`2450`	`2450`	`*/`
`@@ -2634,8 +2634,8 @@ public function findStartOfStatement($start, $ignore=null)`
`2634`	`2634`	`/**`
`2635`	`2635`	`* Returns the position of the last non-whitespace token in a statement.`
`2636`	`2636`	`*`
`2637`		`- * @param int $start The position to start searching from in the token stack.`
`2638`		`- * @param int\|string\|array $ignore Token types that should not be considered stop points.`
	`2637`	`+ * @param int $start The position to start searching from in the token stack.`
	`2638`	`+ * @param int\|string\|array\|null $ignore Token types that should not be considered stop points.`
`2639`	`2639`	`*`
`2640`	`2640`	`* @return int`
`2641`	`2641`	`*/`
`@@ -2756,7 +2756,7 @@ public function findEndOfStatement($start, $ignore=null)`
`2756`	`2756`	`* token stack.`
`2757`	`2757`	`* @param bool $exclude If true, find the token that is NOT of`
`2758`	`2758`	`* the types specified in $types.`
`2759`		`- * @param string $value The value that the token must be equal to.`
	`2759`	`+ * @param string\|null $value The value that the token must be equal to.`
`2760`	`2760`	`* If value is omitted, tokens with any value will`
`2761`	`2761`	`* be returned.`
`2762`	`2762`	`*`
Original file line number	Diff line number	Diff line change
`@@ -110,8 +110,8 @@ public function __construct(Config $config, Ruleset $ruleset)`
`110`	`110`	`* If a file object has already been created, it can be passed here.`
`111`	`111`	`* If it is left NULL, it will be created when accessed.`
`112`	`112`	`*`
`113`		`- * @param string $path The path to the file being added.`
`114`		`- * @param \PHP_CodeSniffer\Files\File $file The file being added.`
	`113`	`+ * @param string $path The path to the file being added.`
	`114`	`+ * @param \PHP_CodeSniffer\Files\File\|null $file The file being added.`
`115`	`115`	`*`
`116`	`116`	`* @return void`
`117`	`117`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -222,10 +222,10 @@ public function fixFile()`
`222`	`222`	`/**`
`223`	`223`	`* Generates a text diff of the original file and the new content.`
`224`	`224`	`*`
`225`		`- * @param string $filePath Optional file path to diff the file against.`
`226`		`- * If not specified, the original version of the`
`227`		`- * file will be used.`
`228`		`- * @param boolean $colors Print coloured output or not.`
	`225`	`+ * @param string\|null $filePath Optional file path to diff the file against.`
	`226`	`+ * If not specified, the original version of the`
	`227`	`+ * file will be used.`
	`228`	`+ * @param boolean $colors Print coloured output or not.`
`229`	`229`	`*`
`230`	`230`	`* @return string`
`231`	`231`	`*`
`@@ -698,10 +698,10 @@ public function revertToken($stackPtr)`
`698`	`698`	`/**`
`699`	`699`	`* Replace the content of a token with a part of its current content.`
`700`	`700`	`*`
`701`		`- * @param int $stackPtr The position of the token in the token stack.`
`702`		`- * @param int $start The first character to keep.`
`703`		`- * @param int $length The number of characters to keep. If NULL, the content of`
`704`		`- * the token from $start to the end of the content is kept.`
	`701`	`+ * @param int $stackPtr The position of the token in the token stack.`
	`702`	`+ * @param int $start The first character to keep.`
	`703`	`+ * @param int\|null $length The number of characters to keep. If NULL, the content of`
	`704`	`+ * the token from $start to the end of the content is kept.`
`705`	`705`	`*`
`706`	`706`	`* @return bool If the change was accepted.`
`707`	`707`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -1698,8 +1698,8 @@ public function setSniffProperty($sniffClass, $name, $settings)`
`1698`	`1698`	`* Optionally takes a listener to get ignore patterns specified`
`1699`	`1699`	`* for that sniff only.`
`1700`	`1700`	`*`
`1701`		`- * @param string $listener The listener to get patterns for. If NULL, all`
`1702`		`- * patterns are returned.`
	`1701`	`+ * @param string\|null $listener The listener to get patterns for. If NULL, all`
	`1702`	`+ * patterns are returned.`
`1703`	`1703`	`*`
`1704`	`1704`	`* @return array`
`1705`	`1705`	`*/`
`@@ -1724,8 +1724,8 @@ public function getIgnorePatterns($listener=null)`
`1724`	`1724`	`* Optionally takes a listener to get include patterns specified`
`1725`	`1725`	`* for that sniff only.`
`1726`	`1726`	`*`
`1727`		`- * @param string $listener The listener to get patterns for. If NULL, all`
`1728`		`- * patterns are returned.`
	`1727`	`+ * @param string\|null $listener The listener to get patterns for. If NULL, all`
	`1728`	`+ * patterns are returned.`
`1729`	`1729`	`*`
`1730`	`1730`	`* @return array`
`1731`	`1731`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -92,7 +92,7 @@ public function process(File $phpcsFile, $stackPtr)`
`92`	`92`	`* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.`
`93`	`93`	`* @param int $stackPtr The position of the current token`
`94`	`94`	`* in the stack passed in $tokens.`
`95`		`- * @param int $end The token where checking should end.`
	`95`	`+ * @param int\|null $end The token where checking should end.`
`96`	`96`	`* If NULL, the entire file will be checked.`
`97`	`97`	`*`
`98`	`98`	`* @return int`
Original file line number	Diff line number	Diff line change
`@@ -53,7 +53,7 @@ public function __construct()`
`53`	`53`	`* @param int $stackPtr The position of the forbidden function`
`54`	`54`	`* in the token array.`
`55`	`55`	`* @param string $function The name of the forbidden function.`
`56`		`- * @param string $pattern The pattern used for the match.`
	`56`	`+ * @param string\|null $pattern The pattern used for the match.`
`57`	`57`	`*`
`58`	`58`	`* @return void`
`59`	`59`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -206,7 +206,7 @@ public function process(File $phpcsFile, $stackPtr)`
`206`	`206`	`* @param int $stackPtr The position of the forbidden function`
`207`	`207`	`* in the token array.`
`208`	`208`	`* @param string $function The name of the forbidden function.`
`209`		`- * @param string $pattern The pattern used for the match.`
	`209`	`+ * @param string\|null $pattern The pattern used for the match.`
`210`	`210`	`*`
`211`	`211`	`* @return void`
`212`	`212`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -300,8 +300,8 @@ public static function save()`
`300`	`300`	`/**`
`301`	`301`	`* Retrieves a single entry from the cache.`
`302`	`302`	`*`
`303`		`- * @param string $key The key of the data to get. If NULL,`
`304`		`- * everything in the cache is returned.`
	`303`	`+ * @param string\|null $key The key of the data to get. If NULL,`
	`304`	`+ * everything in the cache is returned.`
`305`	`305`	`*`
`306`	`306`	`* @return mixed`
`307`	`307`	`*/`
`@@ -323,9 +323,9 @@ public static function get($key=null)`
`323`	`323`	`/**`
`324`	`324`	`* Retrieves a single entry from the cache.`
`325`	`325`	`*`
`326`		`- * @param string $key The key of the data to set. If NULL,`
`327`		`- * sets the entire cache.`
`328`		`- * @param mixed $value The value to set.`
	`326`	`+ * @param string\|null $key The key of the data to set. If NULL,`
	`327`	`+ * sets the entire cache.`
	`328`	`+ * @param mixed $value The value to set.`
`329`	`329`	`*`
`330`	`330`	`* @return void`
`331`	`331`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -804,8 +804,8 @@ public static function tokenName($token)`
`804`	`804`	`* @param array<int\|string> $tokens The token types to get the highest weighted`
`805`	`805`	`* type for.`
`806`	`806`	`*`
`807`		`- * @return int The highest weighted token.`
`808`		`- * On equal "weight", returns the first token of that particular weight.`
	`807`	`+ * @return int\|string The highest weighted token.`
	`808`	`+ * On equal "weight", returns the first token of that particular weight.`
`809`	`809`	`*/`
`810`	`810`	`public static function getHighestWeightedToken(array $tokens)`
`811`	`811`	`{`