PHPCSStandards · jrfnl · Oct 25, 2022 · Oct 15, 2022
diff --git a/PHPCSUtils/Exceptions/InvalidTokenArray.php b/PHPCSUtils/Exceptions/InvalidTokenArray.php
@@ -23,6 +23,8 @@ final class InvalidTokenArray extends RuntimeException
     /**
      * Create a new invalid token array exception with a standardized text.
      *
+     * @since 1.0.0-alpha4
+     *
      * @param string $name The name of the token array requested.
      *
      * @return \PHPCSUtils\Exceptions\InvalidTokenArray

diff --git a/PHPCSUtils/Fixers/SpacesFixer.php b/PHPCSUtils/Fixers/SpacesFixer.php
@@ -51,7 +51,7 @@ final class SpacesFixer
      *                                                    when reporting an issue.
      * @param int                         $secondPtr      The stack pointer to the second token.
      *                                                    This token can be before or after the `$stackPtr`,
-     *                                                    but should only be seperated from the `$stackPtr`
+     *                                                    but should only be separated from the `$stackPtr`
      *                                                    by whitespace and/or comments/annotations.
      * @param string|int                  $expectedSpaces Number of spaces to enforce.
      *                                                    Valid values:

diff --git a/PHPCSUtils/TestUtils/UtilityMethodTestCase.php b/PHPCSUtils/TestUtils/UtilityMethodTestCase.php
@@ -25,7 +25,7 @@
  * This class is compatible with PHP_CodeSniffer 3.x and contains preliminary compatibility with 4.x
  * based on its currently known state/roadmap.
  *
- * This class is compatible with {@link http://phpunit.de/ PHPUnit} 4.5 - 9.x providing the PHPCSUtils
+ * This class is compatible with {@link https://phpunit.de/ PHPUnit} 4.5 - 9.x providing the PHPCSUtils
  * autoload file is included in the test bootstrap. For more information about that, please consult
  * the project's {@link https://github.com/PHPCSStandards/PHPCSUtils/blob/develop/README.md README}.
  *

diff --git a/PHPCSUtils/Tokens/Collections.php b/PHPCSUtils/Tokens/Collections.php
@@ -122,10 +122,10 @@ final class Collections
     /**
      * DEPRECATED: Tokens which are used to create arrays.
      *
-     * @see \PHPCSUtils\Tokens\Collections::arrayOpenTokensBC() Related method to retrieve only the "open"
-     *                                                          tokens used for arrays (PHPCS cross-version).
+     * @see \PHPCSUtils\Tokens\Collections::arrayOpenTokensBC() Related method to retrieve only the "open" tokens
+     *                                                          used for arrays (PHPCS cross-version compatible).
      * @see \PHPCSUtils\Tokens\Collections::arrayTokensBC()     Related method to retrieve tokens used
-     *                                                          for arrays (PHPCS cross-version).
+     *                                                          for arrays (PHPCS cross-version compatible).
      * @see \PHPCSUtils\Tokens\Collections::shortArrayTokens()  Related method to retrieve only tokens used
      *                                                          for short arrays.
      *
@@ -148,6 +148,11 @@ final class Collections
      * intermittent tokenizer issues related to the retokenization to `T_OPEN_SHORT_ARRAY`.
      * Should only be used selectively.
      *
+     * @see \PHPCSUtils\Tokens\Collections::arrayOpenTokensBC()  Related method to retrieve only the "open" tokens
+     *                                                           used for arrays (PHPCS cross-version compatible).
+     * @see \PHPCSUtils\Tokens\Collections::shortArrayTokensBC() Related method to retrieve only tokens used
+     *                                                           for short arrays (PHPCS cross-version compatible).
+     *
      * @since 1.0.0-alpha1
      *
      * @deprecated 1.0.0-alpha4 Use the {@see Collections::arrayTokensBC()} method instead.
@@ -303,7 +308,8 @@ final class Collections
      *
      * @since 1.0.0-alpha3
      *
-     * @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\BackCompat\BCTokens::magicConstants()} method instead.
+     * @deprecated 1.0.0-alpha4 Use the {@see \PHP_CodeSniffer\Util\Tokens::$magicConstants} property
+     *                          or the {@see \PHPCSUtils\BackCompat\BCTokens::magicConstants()} method instead.
      *
      * @var array <int|string> => <int|string>
      */
@@ -342,7 +348,7 @@ final class Collections
      * but are not used yet (the PHP 8.0 tokenization is "undone" in PHPCS).
      * As of PHPCS 4.0.0, these tokens _will_ be used and the PHP 8.0 tokenization is respected.
      *
-     * @link https://wiki.php.net/rfc/namespaced_names_as_token
+     * @link https://wiki.php.net/rfc/namespaced_names_as_token PHP RFC on namespaced names as single token
      *
      * @since 1.0.0-alpha4 Use the {@see Collections::nameTokens()} method for access.
      *

diff --git a/PHPCSUtils/Tokens/TokenHelper.php b/PHPCSUtils/Tokens/TokenHelper.php
@@ -39,8 +39,8 @@ final class TokenHelper
      * PHP-Parser polyfilled tokens will always have a negative integer value < 0, which is how
      * these are filtered out.}
      *
-     * @link https://github.com/sebastianbergmann/php-code-coverage/issues/798
-     * @link https://github.com/nikic/PHP-Parser/blob/master/lib/PhpParser/Lexer.php
+     * @link https://github.com/sebastianbergmann/php-code-coverage/issues/798       PHP-Code-Coverage#798
+     * @link https://github.com/nikic/PHP-Parser/blob/master/lib/PhpParser/Lexer.php PHP-Parser Lexer code
      *
      * @since 1.0.0-alpha4
      *

diff --git a/PHPCSUtils/Utils/Context.php b/PHPCSUtils/Utils/Context.php
@@ -22,7 +22,7 @@
  * - A sniff looking for incrementor/decrementors may want to disregard these when used
  *   as the third expression in a `for()` condition.
  *
- * @since 1.0.0
+ * @since 1.0.0-alpha4
  */
 final class Context
 {
@@ -34,7 +34,7 @@ final class Context
      * For more complex/combined queries, it is recommended to call the {@see Parentheses::getLastOwner()}
      * method directly._
      *
-     * @since 1.0.0
+     * @since 1.0.0-alpha4
      *
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
      * @param int                         $stackPtr  The position of the token we are checking.
@@ -53,7 +53,7 @@ public static function inEmpty(File $phpcsFile, $stackPtr)
      * For more complex/combined queries, it is recommended to call the {@see Parentheses::getLastOwner()}
      * method directly._
      *
-     * @since 1.0.0
+     * @since 1.0.0-alpha4
      *
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
      * @param int                         $stackPtr  The position of the token we are checking.
@@ -72,7 +72,7 @@ public static function inIsset(File $phpcsFile, $stackPtr)
      * For more complex/combined queries, it is recommended to call the {@see Parentheses::getLastOwner()}
      * method directly._
      *
-     * @since 1.0.0
+     * @since 1.0.0-alpha4
      *
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
      * @param int                         $stackPtr  The position of the token we are checking.
@@ -115,7 +115,7 @@ public static function inAttribute(File $phpcsFile, $stackPtr)
      * Check whether an arbitrary token is in a foreach condition and if so, in which part:
      * before or after the "as".
      *
-     * @since 1.0.0
+     * @since 1.0.0-alpha4
      *
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
      * @param int                         $stackPtr  The position of the token we are checking.
@@ -167,7 +167,7 @@ public static function inForeachCondition(File $phpcsFile, $stackPtr)
      * Note: the semicolons separating the conditions are regarded as belonging with the
      * expression before it.
      *
-     * @since 1.0.0
+     * @since 1.0.0-alpha4
      *
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
      * @param int                         $stackPtr  The position of the token we are checking.

diff --git a/PHPCSUtils/Utils/FunctionDeclarations.php b/PHPCSUtils/Utils/FunctionDeclarations.php
@@ -459,7 +459,11 @@ public static function getParameters(File $phpcsFile, $stackPtr)
 
         for ($i = $paramStart; $i <= $closer; $i++) {
             if (isset($parameterTypeTokens[$tokens[$i]['code']]) === true
-                // Self and parent are valid, static invalid, but was probably intended as type declaration.
+                /*
+                 * Self and parent are valid, static invalid, but was probably intended as type declaration.
+                 * Note: constructor property promotion does not support static properties, so this should
+                 * still be a valid assumption.
+                 */
                 || $tokens[$i]['code'] === \T_STATIC
             ) {
                 if ($typeHintToken === false) {

diff --git a/PHPCSUtils/Utils/NamingConventions.php b/PHPCSUtils/Utils/NamingConventions.php
@@ -16,8 +16,9 @@
  * Identifier names in PHP are:
  * - {@link https://www.php.net/language.namespaces.definition namespace} names;
  * - {@link https://www.php.net/language.oop5.basic class},
- *   {@link https://www.php.net/language.oop5.traits trait} and
- *   {@link https://www.php.net/language.oop5.interfaces interface} names;
+ *   {@link https://www.php.net/language.oop5.traits trait},
+ *   {@link https://www.php.net/language.oop5.interfaces interface} and
+ *   {@link https://www.php.net/language.types.enumerations enum} names;
  * - {@link https://www.php.net/functions.user-defined function and method} names;
  * - {@link https://www.php.net/language.variables.basics variable} names;
  * - {@link https://www.php.net/language.constants constant} names.

diff --git a/PHPCSUtils/Utils/Numbers.php b/PHPCSUtils/Utils/Numbers.php
@@ -159,7 +159,7 @@ public static function getCompleteNumber(File $phpcsFile, $stackPtr)
     /**
      * Get the decimal number value of a numeric string.
      *
-     * Takes PHP 7.4 numeric literal separators in numbers into account.
+     * Takes PHP 7.4 numeric literal separators and explicit octal literals in numbers into account.
      *
      * @since 1.0.0
      *
@@ -282,7 +282,7 @@ public static function isBinaryInt($textString)
     /**
      * Verify whether the contents of an arbitrary string represents an octal integer.
      *
-     * Takes PHP 7.4 numeric literal separators in numbers into account.
+     * Takes PHP 7.4 numeric literal separators and explicit octal literals in numbers into account.
      *
      * @since 1.0.0
      *

diff --git a/PHPCSUtils/Utils/Parentheses.php b/PHPCSUtils/Utils/Parentheses.php
@@ -33,7 +33,7 @@ final class Parentheses
      *
      * - `T_ISSET`, `T_UNSET`, `T_EMPTY`, `T_EXIT` and `T_EVAL` are not PHPCS native parentheses
      *    owners, but are considered such for the purposes of this class.
-     *    Also {@see https://github.com/squizlabs/PHP_CodeSniffer/issues/3118}.
+     *    Also see {@link https://github.com/squizlabs/PHP_CodeSniffer/issues/3118 PHPCS#3118}.
      *
      * @since 1.0.0-alpha4
      *

diff --git a/PHPCSUtils/Utils/PassedParameters.php b/PHPCSUtils/Utils/PassedParameters.php
@@ -64,6 +64,7 @@ final class PassedParameters
      *   language constructs have "parameters".
      *
      * @since 1.0.0
+     * @since 1.0.0-alpha4 Added the `$isShortArray` parameter.
      * @since 1.0.0-alpha4 Added support for PHP 8.0 identifier name tokenization.
      * @since 1.0.0-alpha4 Added defensive coding against PHP 8.1 first class callables
      *                     being passed as if they were function calls.
@@ -156,6 +157,7 @@ public static function hasParameters(File $phpcsFile, $stackPtr, $isShortArray =
      * See {@see PassedParameters::hasParameters()} for information on the supported constructs.
      *
      * @since 1.0.0
+     * @since 1.0.0-alpha4 Added the `$limit` and `$isShortArray` parameters.
      * @since 1.0.0-alpha4 Added support for PHP 8.0 function calls with named arguments by introducing
      *                     the `'name'` and `'name_token'` index keys as well as using the name
      *                     as the index for the top-level array for named parameters.
@@ -165,6 +167,8 @@ public static function hasParameters(File $phpcsFile, $stackPtr, $isShortArray =
      *                                                  language construct or array open token.
      * @param int                         $limit        Optional. Limit the parameter retrieval to the first #
      *                                                  parameters/array entries.
+     *                                                  Use with care on function calls, as this can break
+     *                                                  support for named parameters!
      * @param true|null                   $isShortArray Optional. Short-circuit the short array check for
      *                                                  `T_OPEN_SHORT_ARRAY` tokens if it isn't necessary.
      *                                                  Efficiency tweak for when this has already been established,
@@ -361,6 +365,7 @@ public static function getParameters(File $phpcsFile, $stackPtr, $limit = 0, $is
      *                                                already retrieved.
      *
      * @since 1.0.0
+     * @since 1.0.0-alpha4 Added the `$paramNames` parameter.
      *
      * @param \PHP_CodeSniffer\Files\File $phpcsFile   The file where this token was found.
      * @param int                         $stackPtr    The position of function call name,
@@ -445,18 +450,18 @@ public static function getParameterCount(File $phpcsFile, $stackPtr)
     /**
      * Get information on a specific function call parameter passed.
      *
-     * This is an efficiency method to correcty handle positional versus named parameters
+     * This is an efficiency method to correctly handle positional versus named parameters
      * for function calls when multiple parameters need to be examined.
      *
      * See {@see PassedParameters::hasParameters()} for information on the supported constructs.
      *
-     * @since 1.0.0
+     * @since 1.0.0-alpha4
      *
      * @param array           $parameters  The output of a previous call to {@see PassedParameters::getParameters()}.
      * @param int             $paramOffset The 1-based index position of the parameter to retrieve.
      * @param string|string[] $paramNames  Either the name of the target parameter to retrieve
      *                                     as a string or an array of names for the same target parameter.
-     *                                     An arrays of names is supported to allow for functions
+     *                                     An array of names is supported to allow for functions
      *                                     for which the parameter names have undergone name
      *                                     changes over time.
      *                                     The name will take precedence over the offset.

diff --git a/PHPCSUtils/Utils/TextStrings.php b/PHPCSUtils/Utils/TextStrings.php
@@ -173,7 +173,7 @@ public static function getEndOfCompleteTextString(File $phpcsFile, $stackPtr)
     /**
      * Strip text delimiter quotes from an arbitrary text string.
      *
-     * Intended for use with the "contents" of a `T_CONSTANT_ENCAPSED_STRING` / `T_DOUBLE_QUOTED_STRING`.
+     * Intended for use with the "content" of a `T_CONSTANT_ENCAPSED_STRING` / `T_DOUBLE_QUOTED_STRING`.
      *
      * - Prevents stripping mis-matched quotes.
      * - Prevents stripping quotes from the textual content of the text string.
@@ -195,6 +195,8 @@ public static function stripQuotes($textString)
      * Note: this function gets the complete variables/expressions _as they are embedded_,
      * i.e. including potential curly brace wrappers, array access, method calls etc.
      *
+     * @since 1.0.0-alpha4
+     *
      * @param string $text The contents of a T_DOUBLE_QUOTED_STRING or T_HEREDOC token.
      *
      * @return array<int, string> Array of encountered variable names/expressions with the offset at which
@@ -208,6 +210,8 @@ public static function getEmbeds($text)
     /**
      * Strip embedded variables/expressions from an arbitrary string.
      *
+     * @since 1.0.0-alpha4
+     *
      * @param string $text The contents of a T_DOUBLE_QUOTED_STRING or T_HEREDOC token.
      *
      * @return string String without variables/expressions in it.
@@ -230,8 +234,11 @@ public static function stripEmbeds($text)
      *
      * This method handles all types of embeds, including recognition of whether an embed is escaped or not.
      *
-     * @link https://www.php.net/manual/en/language.types.string.php#language.types.string.parsing
-     * @link https://wiki.php.net/rfc/deprecate_dollar_brace_string_interpolation
+     * @link https://www.php.net/language.types.string#language.types.string.parsing PHP Manual on string parsing
+     * @link https://wiki.php.net/rfc/deprecate_dollar_brace_string_interpolation    PHP RFC on deprecating select
+     *                                                                               string interpolation syntaxes
+     *
+     * @since 1.0.0-alpha4
      *
      * @param string $text The contents of a T_DOUBLE_QUOTED_STRING or T_HEREDOC token.
      *

diff --git a/PHPCSUtils/Utils/Variables.php b/PHPCSUtils/Utils/Variables.php
@@ -37,9 +37,9 @@ final class Variables
      * The variables names are set without the leading dollar sign to allow this array
      * to be used with array index keys as well. Think: `'_GET'` in `$GLOBALS['_GET']`.}
      *
-     * @since 1.0.0
+     * @link https://php.net/reserved.variables PHP Manual on reserved variables
      *
-     * @link http://php.net/reserved.variables PHP Manual on reserved variables
+     * @since 1.0.0
      *
      * @var array <string> => <bool>
      */

diff --git a/Tests/BackCompat/BCFile/FindStartOfStatementTest.php b/Tests/BackCompat/BCFile/FindStartOfStatementTest.php
@@ -462,7 +462,7 @@ public function testOpenTagWithEcho()
     /**
      * Test object call on result of static function call with arrow function as parameter and wrapped within an array.
      *
-     * @link https://github.com/squizlabs/php_codesniffer/issues/2849
+     * @link https://github.com/squizlabs/PHP_CodeSniffer/issues/2849
      * @link https://github.com/squizlabs/PHP_CodeSniffer/commit/fbf67efc3fc0c2a355f5585d49f4f6fe160ff2f9
      *
      * @return void

diff --git a/Tests/BackCompat/BCTokens/UnchangedTokenArraysTest.php b/Tests/BackCompat/BCTokens/UnchangedTokenArraysTest.php
@@ -370,9 +370,9 @@ final class UnchangedTokenArraysTest extends TestCase
     /**
      * Tokens representing context sensitive keywords in PHP.
      *
-     * @var array<int|string, int|string>
+     * @link https://wiki.php.net/rfc/context_sensitive_lexer
      *
-     * https://wiki.php.net/rfc/context_sensitive_lexer
+     * @var array<int|string, int|string>
      */
     private $contextSensitiveKeywords = [
         \T_ABSTRACT     => \T_ABSTRACT,

diff --git a/Tests/Fixers/SpacesFixer/SpacesFixerTestCase.php b/Tests/Fixers/SpacesFixer/SpacesFixerTestCase.php
@@ -14,11 +14,7 @@
 use PHPCSUtils\TestUtils\UtilityMethodTestCase;
 
 /**
- * Tests for the \PHPCSUtils\Fixers\SpacesFixer::checkAndFix() method.
- *
- * @covers \PHPCSUtils\Fixers\SpacesFixer::checkAndFix
- *
- * @group fixers
+ * Test case for the \PHPCSUtils\Fixers\SpacesFixer::checkAndFix() method.
  *
  * @since 1.0.0
  */
@@ -109,6 +105,8 @@ public static function setUpTestFile()
     /**
      * Test that no violation is reported for a test case complying with the correct number of spaces.
      *
+     * @covers \PHPCSUtils\Fixers\SpacesFixer::checkAndFix
+     *
      * @dataProvider dataCheckAndFixNoError
      *
      * @param string $testMarker The comment which prefaces the target token in the test file.
@@ -175,6 +173,8 @@ public function dataCheckAndFixNoError()
     /**
      * Test that violations are correctly reported.
      *
+     * @covers \PHPCSUtils\Fixers\SpacesFixer::checkAndFix
+     *
      * @dataProvider dataCheckAndFix
      *
      * @param string $testMarker The comment which prefaces the target token in the test file.
@@ -258,6 +258,8 @@ public function dataCheckAndFix()
     /**
      * Test that the fixes are correctly made.
      *
+     * @covers \PHPCSUtils\Fixers\SpacesFixer::checkAndFix
+     *
      * @return void
      */
     public function testFixesMade()

diff --git a/Tests/Utils/FunctionDeclarations/IsArrowFunction2926Test.php b/Tests/Utils/FunctionDeclarations/IsArrowFunction2926Test.php
@@ -21,7 +21,7 @@
  *
  * These tests are based on the `Tokenizer/BackfillFnTokenTest` file in PHPCS itself.
  *
- * @link https://github.com/squizlabs/php_codesniffer/issues/2926
+ * @link https://github.com/squizlabs/PHP_CodeSniffer/issues/2926
  *
  * @covers \PHPCSUtils\Utils\FunctionDeclarations::isArrowFunction
  * @covers \PHPCSUtils\Utils\FunctionDeclarations::getArrowFunctionOpenClose