Merge pull request #553 from PHPCSStandards/feature/various-minor-doc…

…s-updates Docs: improve type info and other minor updates
PHPCSStandards · Feb 1, 2024 · af80d2b · af80d2b
2 parents 79751f2 + f8873a1
commit af80d2b
Show file tree

Hide file tree

Showing 100 changed files with 288 additions and 287 deletions.
diff --git a/PHPCSUtils/BackCompat/BCFile.php b/PHPCSUtils/BackCompat/BCFile.php
@@ -161,7 +161,7 @@ public static function getDeclarationName(File $phpcsFile, $stackPtr)
      *                                           // or FALSE if there is no type hint.
      *   'type_hint_end_token' => integer|false, // The stack pointer to the end of the type hint
      *                                           // or FALSE if there is no type hint.
-     *   'nullable_type'       => boolean,       // TRUE if the var type is preceded by the nullability
+     *   'nullable_type'       => boolean,       // TRUE if the param type is preceded by the nullability
      *                                           // operator.
      *   'comma_token'         => integer|false, // The stack pointer to the comma after the param
      *                                           // or FALSE if this is the last param.
@@ -178,9 +178,9 @@ public static function getDeclarationName(File $phpcsFile, $stackPtr)
      * Parameters declared using PHP 8 constructor property promotion, have these additional array indexes:
      * ```php
      *   'property_visibility' => string,        // The property visibility as declared.
-     *   'visibility_token'    => integer,|false // The stack pointer to the visibility modifier token.
+     *   'visibility_token'    => integer|false, // The stack pointer to the visibility modifier token.
      *                                           // or FALSE if the visibility is not explicitly declared.
-     *   'property_readonly'   => bool,          // TRUE if the readonly keyword was found.
+     *   'property_readonly'   => boolean,       // TRUE if the readonly keyword was found.
      *   'readonly_token'      => integer,       // The stack pointer to the readonly modifier token.
      *                                           // This index will only be set if the property is readonly.
      * ```
@@ -848,8 +848,8 @@ public static function findExtendedClassName(File $phpcsFile, $stackPtr)
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
      * @param int                         $stackPtr  The stack position of the class or enum token.
      *
-     * @return string[]|false Array with names of the implemented interfaces or `FALSE` on
-     *                        error or if there are no implemented interface names.
+     * @return array<string>|false Array with names of the implemented interfaces or `FALSE` on
+     *                             error or if there are no implemented interface names.
      */
     public static function findImplementedInterfaceNames(File $phpcsFile, $stackPtr)
     {

diff --git a/PHPCSUtils/Internal/IsShortArrayOrListWithCache.php b/PHPCSUtils/Internal/IsShortArrayOrListWithCache.php
@@ -138,7 +138,7 @@ public static function isShortList(File $phpcsFile, $stackPtr)
      *
      * @return string|false The type of construct this bracket was determined to be.
      *                      Either 'short array', 'short list' or 'square brackets'.
-     *                      Or FALSE is this was not a bracket token.
+     *                      Or FALSE if this was not a bracket token.
      */
     public static function getType(File $phpcsFile, $stackPtr)
     {

diff --git a/PHPCSUtils/TestUtils/UtilityMethodTestCase.php b/PHPCSUtils/TestUtils/UtilityMethodTestCase.php
@@ -172,7 +172,7 @@ abstract class UtilityMethodTestCase extends TestCase
      *
      * @since 1.0.0
      *
-     * @var string[]
+     * @var array<string>
      */
     protected static $selectedSniff = ['Dummy.Dummy.Dummy'];
 
@@ -372,7 +372,7 @@ public static function usesPhp8NameTokens()
      * @param string                       $commentString The complete delimiter comment to look for as a string.
      *                                                    This string should include the comment opener and closer.
      * @param int|string|array<int|string> $tokenType     The type of token(s) to look for.
-     * @param string                       $tokenContent  Optional. The token content for the target token.
+     * @param string|null                  $tokenContent  Optional. The token content for the target token.
      *
      * @return int
      *

diff --git a/PHPCSUtils/Utils/ObjectDeclarations.php b/PHPCSUtils/Utils/ObjectDeclarations.php
@@ -272,8 +272,8 @@ public static function findExtendedClassName(File $phpcsFile, $stackPtr)
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
      * @param int                         $stackPtr  The stack position of the class or enum token.
      *
-     * @return string[]|false Array with names of the implemented interfaces or `FALSE` on
-     *                        error or if there are no implemented interface names.
+     * @return array<string>|false Array with names of the implemented interfaces or `FALSE` on
+     *                             error or if there are no implemented interface names.
      */
     public static function findImplementedInterfaceNames(File $phpcsFile, $stackPtr)
     {
@@ -290,8 +290,8 @@ public static function findImplementedInterfaceNames(File $phpcsFile, $stackPtr)
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
      * @param int                         $stackPtr  The stack position of the interface keyword.
      *
-     * @return string[]|false Array with names of the extended interfaces or `FALSE` on
-     *                        error or if there are no extended interface names.
+     * @return array<string>|false Array with names of the extended interfaces or `FALSE` on
+     *                             error or if there are no extended interface names.
      */
     public static function findExtendedInterfaceNames(File $phpcsFile, $stackPtr)
     {
@@ -317,8 +317,8 @@ public static function findExtendedInterfaceNames(File $phpcsFile, $stackPtr)
      * @param array<int|string, int|string> $allowedFor Array of OO types for which use of the keyword
      *                                                  is allowed.
      *
-     * @return string[]|false Returns an array of names or `FALSE` on error or when the object
-     *                        being declared does not extend/implement another object.
+     * @return array<string>|false Returns an array of names or `FALSE` on error or when the object
+     *                             being declared does not extend/implement another object.
      */
     private static function findNames(File $phpcsFile, $stackPtr, $keyword, array $allowedFor)
     {

diff --git a/PHPCSUtils/Utils/PassedParameters.php b/PHPCSUtils/Utils/PassedParameters.php
@@ -367,7 +367,7 @@ public static function getParameters(File $phpcsFile, $stackPtr, $limit = 0, $is
      * @param int                         $stackPtr    The position of function call name,
      *                                                 language construct or array open token.
      * @param int                         $paramOffset The 1-based index position of the parameter to retrieve.
-     * @param string|string[]             $paramNames  Optional. Either the name of the target parameter
+     * @param string|array<string>        $paramNames  Optional. Either the name of the target parameter
      *                                                 to retrieve as a string or an array of names for the
      *                                                 same target parameter.
      *                                                 Only relevant for function calls.
@@ -457,7 +457,7 @@ public static function getParameterCount(File $phpcsFile, $stackPtr)
      *                                                                  {@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
+     * @param string|array<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 array of names is supported to allow for functions

diff --git a/Tests/AbstractSniffs/AbstractArrayDeclaration/AbstractArrayDeclarationSniffTest.php b/Tests/AbstractSniffs/AbstractArrayDeclaration/AbstractArrayDeclarationSniffTest.php
@@ -31,7 +31,7 @@ final class AbstractArrayDeclarationSniffTest extends PolyfilledTestCase
      * Needed for PHPUnit cross-version support as PHPUnit 4.x does not have a
      * `setMethodsExcept()` method yet.
      *
-     * @var string[]
+     * @var array<string>
      */
     public $methodsToMock = [
         'processOpenClose',

diff --git a/Tests/AbstractSniffs/AbstractArrayDeclaration/GetActualArrayKeyTest.php b/Tests/AbstractSniffs/AbstractArrayDeclaration/GetActualArrayKeyTest.php
@@ -69,7 +69,7 @@ public function testGetActualArrayKey($testMarker, $expected, $expectedFrom)
      *
      * @see testGetActualArrayKey() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, int|string|null>>
      */
     public static function dataGetActualArrayKey()
     {

diff --git a/Tests/BackCompat/BCFile/FindImplementedInterfaceNamesTest.php b/Tests/BackCompat/BCFile/FindImplementedInterfaceNamesTest.php
@@ -98,7 +98,7 @@ public function testFindImplementedInterfaceNames($identifier, $expected)
      *
      * @see testFindImplementedInterfaceNames()
      *
-     * @return array<string, array<string, string|array<string>>>
+     * @return array<string, array<string, string|array<string>|false>>
      */
     public static function dataImplementedInterface()
     {

diff --git a/Tests/BackCompat/BCFile/GetMethodPropertiesTest.php b/Tests/BackCompat/BCFile/GetMethodPropertiesTest.php
@@ -41,7 +41,7 @@ class GetMethodPropertiesTest extends UtilityMethodTestCase
      * @dataProvider dataNotAFunctionException
      *
      * @param string                       $commentString   The comment which preceeds the test.
-     * @param string|int|array<int|string> $targetTokenType The token type to search for after $commentString.
+     * @param int|string|array<int|string> $targetTokenType The token type to search for after $commentString.
      *
      * @return void
      */
@@ -1203,7 +1203,7 @@ public function testFunctionDeclarationNestedInTernaryPHPCS2975()
      *
      * @param string                         $commentString The comment which preceeds the test.
      * @param array<string, string|int|bool> $expected      The expected function output.
-     * @param string|int|array<int|string>   $targetType    Optional. The token type to search for after $commentString.
+     * @param int|string|array<int|string>   $targetType    Optional. The token type to search for after $commentString.
      *                                                      Defaults to the function/closure tokens.
      *
      * @return void

diff --git a/Tests/BackCompat/BCTokens/UnchangedTokenArraysTest.php b/Tests/BackCompat/BCTokens/UnchangedTokenArraysTest.php
@@ -452,8 +452,8 @@ final class UnchangedTokenArraysTest extends TestCase
      *
      * @dataProvider dataUnchangedTokenArrays
      *
-     * @param string $name     The token array name.
-     * @param array  $expected The token array content.
+     * @param string                        $name     The token array name.
+     * @param array<int|string, int|string> $expected The token array content.
      *
      * @return void
      */
@@ -467,7 +467,7 @@ public function testUnchangedTokenArrays($name, $expected)
      *
      * @see testUnchangedTokenArrays() For the array format.
      *
-     * @return array
+     * @return array<string, array<int|string, int|string>>
      */
     public static function dataUnchangedTokenArrays()
     {

diff --git a/Tests/ExpectWithConsecutiveArgs.php b/Tests/ExpectWithConsecutiveArgs.php
@@ -25,10 +25,11 @@ trait ExpectWithConsecutiveArgs
     /**
      * PHPUnit cross-version helper method to test the arguments passed to a method in a mocked object.
      *
-     * @param object $mockObject   The object mock.
-     * @param object $countMatcher Matcher for number of time the method is expected to be called.
-     * @param string $methodName   The name of the method on which to set the expectations.
-     * @param array  $expectedArgs Multi-dimentional array of arguments expected to be passed in consecutive calls.
+     * @param object              $mockObject   The object mock.
+     * @param object              $countMatcher Matcher for number of time the method is expected to be called.
+     * @param string              $methodName   The name of the method on which to set the expectations.
+     * @param array<array<mixed>> $expectedArgs Multi-dimentional array of arguments expected to be passed in
+     *                                          consecutive calls.
      *
      * @return object Expectation object.
      */

diff --git a/Tests/Fixers/SpacesFixer/SpacesFixerAtEOFTest.php b/Tests/Fixers/SpacesFixer/SpacesFixerAtEOFTest.php
@@ -58,7 +58,7 @@ final class SpacesFixerAtEOFTest extends UtilityMethodTestCase
     /**
      * Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).
      *
-     * @var string[]
+     * @var array<string>
      */
     protected static $selectedSniff = ['PHPCSUtils.SpacesFixer.Test'];
 

diff --git a/Tests/Fixers/SpacesFixer/SpacesFixerNewlineTest.php b/Tests/Fixers/SpacesFixer/SpacesFixerNewlineTest.php
@@ -48,7 +48,7 @@ final class SpacesFixerNewlineTest extends SpacesFixerTestCase
     /**
      * The names of the test case(s) in compliance.
      *
-     * @var string[]
+     * @var array<string>
      */
     protected static $compliantCases = [
         'newline-and-trailing-spaces',

diff --git a/Tests/Fixers/SpacesFixer/SpacesFixerNoSpaceTest.php b/Tests/Fixers/SpacesFixer/SpacesFixerNoSpaceTest.php
@@ -48,7 +48,7 @@ final class SpacesFixerNoSpaceTest extends SpacesFixerTestCase
     /**
      * The names of the test case(s) in compliance.
      *
-     * @var string[]
+     * @var array<string>
      */
     protected static $compliantCases = ['no-space'];
 

diff --git a/Tests/Fixers/SpacesFixer/SpacesFixerOneSpaceTest.php b/Tests/Fixers/SpacesFixer/SpacesFixerOneSpaceTest.php
@@ -48,7 +48,7 @@ final class SpacesFixerOneSpaceTest extends SpacesFixerTestCase
     /**
      * The names of the test case(s) in compliance.
      *
-     * @var string[]
+     * @var array<string>
      */
     protected static $compliantCases = [
         'one-space',

diff --git a/Tests/Fixers/SpacesFixer/SpacesFixerTestCase.php b/Tests/Fixers/SpacesFixer/SpacesFixerTestCase.php
@@ -69,7 +69,7 @@ abstract class SpacesFixerTestCase extends UtilityMethodTestCase
      *
      * Important: this MUST be set in the concrete test class!
      *
-     * @var string[]
+     * @var array<string>
      */
     protected static $compliantCases = [];
 
@@ -85,7 +85,7 @@ abstract class SpacesFixerTestCase extends UtilityMethodTestCase
     /**
      * Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).
      *
-     * @var string[]
+     * @var array<string>
      */
     protected static $selectedSniff = ['PHPCSUtils.SpacesFixer.Test'];
 
@@ -109,8 +109,8 @@ public static function setUpTestFile()
      *
      * @dataProvider dataCheckAndFixNoError
      *
-     * @param string $testMarker The comment which prefaces the target token in the test file.
-     * @param array  $expected   Expected error details (for the metric input).
+     * @param string                     $testMarker The comment which prefaces the target token in the test file.
+     * @param array<string, string|bool> $expected   Expected error details (for the metric input).
      *
      * @return void
      */
@@ -154,7 +154,7 @@ public function testCheckAndFixNoError($testMarker, $expected)
      *
      * @see testCheckAndFixNoError() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, string|array<string, string|bool>>>
      */
     public static function dataCheckAndFixNoError()
     {
@@ -177,9 +177,9 @@ public static function dataCheckAndFixNoError()
      *
      * @dataProvider dataCheckAndFix
      *
-     * @param string $testMarker The comment which prefaces the target token in the test file.
-     * @param array  $expected   Expected error details.
-     * @param string $type       The message type to test: 'error' or 'warning'.
+     * @param string                     $testMarker The comment which prefaces the target token in the test file.
+     * @param array<string, string|bool> $expected   Expected error details.
+     * @param string                     $type       The message type to test: 'error' or 'warning'.
      *
      * @return void
      */
@@ -242,7 +242,7 @@ public function testCheckAndFix($testMarker, $expected, $type)
      *
      * @see testCheckAndFix() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, string|array<string, string|bool>>>
      */
     public static function dataCheckAndFix()
     {
@@ -301,7 +301,7 @@ public function testFixesMade()
     /**
      * Helper function holding the base data for the data providers.
      *
-     * @return array<string, array<string, mixed>>
+     * @return array<string, array<string, string|array<string, string|bool>>>
      */
     protected static function getAllData()
     {

diff --git a/Tests/Fixers/SpacesFixer/SpacesFixerTwoSpaceTest.php b/Tests/Fixers/SpacesFixer/SpacesFixerTwoSpaceTest.php
@@ -50,7 +50,7 @@ final class SpacesFixerTwoSpaceTest extends SpacesFixerTestCase
     /**
      * The names of the test case(s) in compliance.
      *
-     * @var string[]
+     * @var array<string>
      */
     protected static $compliantCases = ['two-spaces'];
 

diff --git a/Tests/Fixers/SpacesFixer/TrailingCommentHandlingNewlineTest.php b/Tests/Fixers/SpacesFixer/TrailingCommentHandlingNewlineTest.php
@@ -65,7 +65,7 @@ final class TrailingCommentHandlingNewlineTest extends UtilityMethodTestCase
     /**
      * Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).
      *
-     * @var string[]
+     * @var array<string>
      */
     protected static $selectedSniff = ['PHPCSUtils.SpacesFixer.Test'];
 
@@ -154,7 +154,7 @@ public function testNoFixesMade()
      *
      * @see testCheckAndFixNoError() For the array format.
      *
-     * @return array
+     * @return array<string, array<string>>
      */
     public static function dataCheckAndFixNoError()
     {

diff --git a/Tests/Fixers/SpacesFixer/TrailingCommentHandlingTest.php b/Tests/Fixers/SpacesFixer/TrailingCommentHandlingTest.php
@@ -65,7 +65,7 @@ final class TrailingCommentHandlingTest extends UtilityMethodTestCase
     /**
      * Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).
      *
-     * @var string[]
+     * @var array<string>
      */
     protected static $selectedSniff = ['PHPCSUtils.SpacesFixer.Test'];
 
@@ -74,9 +74,9 @@ final class TrailingCommentHandlingTest extends UtilityMethodTestCase
      *
      * @dataProvider dataCheckAndFix
      *
-     * @param string $testMarker The comment which prefaces the target token in the test file.
-     * @param array  $expected   Expected error details.
-     * @param string $type       The message type to test: 'error' or 'warning'.
+     * @param string                     $testMarker The comment which prefaces the target token in the test file.
+     * @param array<string, string|bool> $expected   Expected error details.
+     * @param string                     $type       The message type to test: 'error' or 'warning'.
      *
      * @return void
      */
@@ -180,7 +180,7 @@ public function testFixesMade()
      *
      * @see testCheckAndFix() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, string|array<string, string|bool>>>
      */
     public static function dataCheckAndFix()
     {

diff --git a/Tests/Internal/Cache/GetClearTest.php b/Tests/Internal/Cache/GetClearTest.php
@@ -280,7 +280,7 @@ public function testGetWillRetrievedPreviouslySetValue($id, $expected)
     /**
      * Data provider.
      *
-     * @return array
+     * @return array<string, array<string, mixed>>
      */
     public static function dataEveryTypeOfInput()
     {

diff --git a/Tests/Internal/Cache/SetTest.php b/Tests/Internal/Cache/SetTest.php
@@ -113,7 +113,7 @@ public function testSetAcceptsEveryTypeOfInput($input)
     /**
      * Data provider.
      *
-     * @return array
+     * @return array<string, array<string, mixed>>
      */
     public static function dataEveryTypeOfInput()
     {
@@ -155,7 +155,7 @@ public function testSetAcceptsIntAndStringIdKeys($id)
     /**
      * Data provider.
      *
-     * @return array
+     * @return array<string, array<string, int|string>>
      */
     public static function dataSetAcceptsIntAndStringIdKeys()
     {