Merge pull request #597 from PHPCSStandards/feature/various-minor-fixes

Various documentation fixes
PHPCSStandards · May 13, 2024 · 8c577be · 8c577be
2 parents 60a360c + 9198d63
commit 8c577be
Show file tree

Hide file tree

Showing 14 changed files with 99 additions and 106 deletions.
diff --git a/PHPCSUtils/TestUtils/UtilityMethodTestCase.php b/PHPCSUtils/TestUtils/UtilityMethodTestCase.php
@@ -84,7 +84,7 @@
  *      *
  *      * @return array
  *      * /
- *     public function dataMyMethod()
+ *     public static function dataMyMethod()
  *     {
  *         return array(
  *             array('/* testTestCaseDescription * /', false),

diff --git a/PHPCSUtils/Utils/Context.php b/PHPCSUtils/Utils/Context.php
@@ -209,7 +209,7 @@ public static function inForCondition(File $phpcsFile, $stackPtr)
             if ($tokens[$i]['level'] !== $level
                 || \count($tokens[$i]['nested_parenthesis']) !== $parens
             ) {
-                // Disregard semi-colons at lower nesting/condition levels.
+                // Disregard semicolons at lower nesting/condition levels.
                 continue;
             }
 

diff --git a/PHPCSUtils/Utils/PassedParameters.php b/PHPCSUtils/Utils/PassedParameters.php
@@ -49,12 +49,11 @@ final class PassedParameters
      *
      * - If passed a `T_STRING`, `T_NAME_FULLY_QUALIFIED`, `T_NAME_RELATIVE`, `T_NAME_QUALIFIED`,
      *   or `T_VARIABLE` stack pointer, it will treat it as a function call.
-     *   If a `T_STRING` or `T_VARIABLE` which is *not* a function call is passed, the behaviour is
-     *   undetermined.
+     *   If a token which is *not* a function call is passed, the behaviour is undetermined.
      * - If passed a `T_ANON_CLASS` stack pointer, it will accept it as a class instantiation.
      * - If passed a `T_SELF`, `T_STATIC` or `T_PARENT` stack pointer, it will accept it as a
-     *   class instantiation function call when used like `new self()` (with or without parenthesis).
-     *   When these hierarchiecal keywords are not preceded by the `new` keyword, parenthesis
+     *   class instantiation function call when used like `new self()` (with or without parentheses).
+     *   When these hierarchiecal keywords are not preceded by the `new` keyword, parentheses
      *   will be required for the token to be accepted.
      * - If passed a `T_ARRAY` or `T_OPEN_SHORT_ARRAY` stack pointer, it will detect
      *   whether the array has values or is empty.

diff --git a/Tests/Utils/Lists/GetAssignmentsTest.php b/Tests/Utils/Lists/GetAssignmentsTest.php
@@ -42,8 +42,8 @@ public function testNonExistentToken()
      *
      * @dataProvider dataNotListToken
      *
-     * @param string           $testMarker  The comment which prefaces the target token in the test file.
-     * @param int|string|array $targetToken The token type(s) to look for.
+     * @param string     $testMarker  The comment which prefaces the target token in the test file.
+     * @param int|string $targetToken The token type(s) to look for.
      *
      * @return void
      */
@@ -60,7 +60,7 @@ public function testNotListToken($testMarker, $targetToken)
      *
      * @see testNotListToken() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, int|string>>
      */
     public static function dataNotListToken()
     {
@@ -81,9 +81,10 @@ public static function dataNotListToken()
      *
      * @dataProvider dataGetAssignments
      *
-     * @param string           $testMarker  The comment which prefaces the target token in the test file.
-     * @param int|string|array $targetToken The token type(s) to look for.
-     * @param array|false      $expected    The expected function return value.
+     * @param string                                     $testMarker  The comment which prefaces the target token
+     *                                                                in the test file.
+     * @param int|string                                 $targetToken The token type(s) to look for.
+     * @param array<int, array<string, int|string|bool>> $expected    The expected function return value.
      *
      * @return void
      */
@@ -124,7 +125,7 @@ public function testGetAssignments($testMarker, $targetToken, $expected)
      *
      * @see testGetAssignments() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, int|string|array<int, array<string, int|string|bool>>>>
      */
     public static function dataGetAssignments()
     {

diff --git a/Tests/Utils/MessageHelper/AddMessageTest.php b/Tests/Utils/MessageHelper/AddMessageTest.php
@@ -49,9 +49,9 @@ final class AddMessageTest extends UtilityMethodTestCase
      * @dataProvider dataAddMessage
      * @covers       ::addMessage
      *
-     * @param string $testMarker The comment which prefaces the target token in the test file.
-     * @param bool   $isError    Whether to test adding an error or a warning.
-     * @param array  $expected   Expected error details.
+     * @param string                     $testMarker The comment which prefaces the target token in the test file.
+     * @param bool                       $isError    Whether to test adding an error or a warning.
+     * @param array<string, bool|string> $expected   Expected error details.
      *
      * @return void
      */
@@ -82,7 +82,7 @@ public function testAddMessage($testMarker, $isError, $expected)
      *
      * @see testAddMessage() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, bool|string|array<string, bool|string>>>
      */
     public static function dataAddMessage()
     {
@@ -114,9 +114,9 @@ public static function dataAddMessage()
      * @dataProvider dataAddFixableMessage
      * @covers       ::addFixableMessage
      *
-     * @param string $testMarker The comment which prefaces the target token in the test file.
-     * @param bool   $isError    Whether to test adding an error or a warning.
-     * @param array  $expected   Expected error details.
+     * @param string                     $testMarker The comment which prefaces the target token in the test file.
+     * @param bool                       $isError    Whether to test adding an error or a warning.
+     * @param array<string, bool|string> $expected   Expected error details.
      *
      * @return void
      */
@@ -148,7 +148,7 @@ public function testAddFixableMessage($testMarker, $isError, $expected)
      *
      * @see testAddFixableMessage() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, bool|string|array<string, bool|string>>>
      */
     public static function dataAddFixableMessage()
     {
@@ -177,9 +177,9 @@ public static function dataAddFixableMessage()
     /**
      * Helper method to verify the expected message details.
      *
-     * @param int   $stackPtr The stack pointer on which the error/warning is expected.
-     * @param bool  $isError  Whether to test adding an error or a warning.
-     * @param array $expected Expected error details.
+     * @param int                            $stackPtr The stack pointer on which the error/warning is expected.
+     * @param bool                           $isError  Whether to test adding an error or a warning.
+     * @param array<string, bool|int|string> $expected Expected error details.
      *
      * @return void
      */

diff --git a/Tests/Utils/Parentheses/ParenthesesTest.php b/Tests/Utils/Parentheses/ParenthesesTest.php
@@ -425,8 +425,8 @@ public function testFunctionNamedFnKeywordNotParenthesesOwner()
      *
      * @dataProvider dataWalkParentheses
      *
-     * @param string $testName        The name of this test as set in the cached $testTokens array.
-     * @param array  $expectedResults Expected function output for the various functions.
+     * @param string                   $testName        The name of this test as set in the cached $testTokens array.
+     * @param array<string, int|false> $expectedResults Expected function output for the various functions.
      *
      * @return void
      */
@@ -456,8 +456,8 @@ public function testGetFirstOpener($testName, $expectedResults)
      *
      * @dataProvider dataWalkParentheses
      *
-     * @param string $testName        The name of this test as set in the cached $testTokens array.
-     * @param array  $expectedResults Expected function output for the various functions.
+     * @param string                   $testName        The name of this test as set in the cached $testTokens array.
+     * @param array<string, int|false> $expectedResults Expected function output for the various functions.
      *
      * @return void
      */
@@ -487,8 +487,8 @@ public function testGetFirstCloser($testName, $expectedResults)
      *
      * @dataProvider dataWalkParentheses
      *
-     * @param string $testName        The name of this test as set in the cached $testTokens array.
-     * @param array  $expectedResults Expected function output for the various functions.
+     * @param string                   $testName        The name of this test as set in the cached $testTokens array.
+     * @param array<string, int|false> $expectedResults Expected function output for the various functions.
      *
      * @return void
      */
@@ -518,8 +518,8 @@ public function testGetFirstOwner($testName, $expectedResults)
      *
      * @dataProvider dataWalkParentheses
      *
-     * @param string $testName        The name of this test as set in the cached $testTokens array.
-     * @param array  $expectedResults Expected function output for the various functions.
+     * @param string                   $testName        The name of this test as set in the cached $testTokens array.
+     * @param array<string, int|false> $expectedResults Expected function output for the various functions.
      *
      * @return void
      */
@@ -549,8 +549,8 @@ public function testGetLastOpener($testName, $expectedResults)
      *
      * @dataProvider dataWalkParentheses
      *
-     * @param string $testName        The name of this test as set in the cached $testTokens array.
-     * @param array  $expectedResults Expected function output for the various functions.
+     * @param string                   $testName        The name of this test as set in the cached $testTokens array.
+     * @param array<string, int|false> $expectedResults Expected function output for the various functions.
      *
      * @return void
      */
@@ -580,8 +580,8 @@ public function testGetLastCloser($testName, $expectedResults)
      *
      * @dataProvider dataWalkParentheses
      *
-     * @param string $testName        The name of this test as set in the cached $testTokens array.
-     * @param array  $expectedResults Expected function output for the various functions.
+     * @param string                   $testName        The name of this test as set in the cached $testTokens array.
+     * @param array<string, int|false> $expectedResults Expected function output for the various functions.
      *
      * @return void
      */
@@ -616,7 +616,7 @@ public function testGetLastOwner($testName, $expectedResults)
      * @see testGetLastCloser()   For the array format.
      * @see testGetLastOwner()    For the array format.
      *
-     * @return array
+     * @return array<string, array<string, string|array<string, int|false>>>
      */
     public static function dataWalkParentheses()
     {
@@ -937,9 +937,9 @@ public static function dataWalkParentheses()
      *
      * @dataProvider dataHasOwner
      *
-     * @param string $testName        The name of this test as set in the cached $testTokens array.
-     * @param array  $expectedResults Array with the owner token type to search for as key
-     *                                and the expected result as a value.
+     * @param string              $testName        The name of this test as set in the cached $testTokens array.
+     * @param array<string, true> $expectedResults Array with the owner token type to search for as key
+     *                                             and the expected result as a value.
      *
      * @return void
      */
@@ -969,7 +969,7 @@ public function testHasOwner($testName, $expectedResults)
      *
      * @see testHasOwner() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, string|array<string, true>>>
      */
     public static function dataHasOwner()
     {
@@ -1191,9 +1191,9 @@ public function testHasOwnerMultipleTypes()
      *
      * @dataProvider dataFirstOwnerIn
      *
-     * @param string    $testName    The name of this test as set in the cached $testTokens array.
-     * @param array     $validOwners Valid owners to test against.
-     * @param int|false $expected    Expected function output
+     * @param string            $testName    The name of this test as set in the cached $testTokens array.
+     * @param array<int|string> $validOwners Valid owners to test against.
+     * @param int|false         $expected    Expected function output
      *
      * @return void
      */
@@ -1213,7 +1213,7 @@ public function testFirstOwnerIn($testName, $validOwners, $expected)
      *
      * @see testFirstOwnerIn() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, int|string|array<int|string>|false>>
      */
     public static function dataFirstOwnerIn()
     {
@@ -1282,9 +1282,9 @@ public static function dataFirstOwnerIn()
      *
      * @dataProvider dataLastOwnerIn
      *
-     * @param string    $testName    The name of this test as set in the cached $testTokens array.
-     * @param array     $validOwners Valid owners to test against.
-     * @param int|false $expected    Expected function output
+     * @param string            $testName    The name of this test as set in the cached $testTokens array.
+     * @param array<int|string> $validOwners Valid owners to test against.
+     * @param int|false         $expected    Expected function output
      *
      * @return void
      */
@@ -1304,7 +1304,7 @@ public function testLastOwnerIn($testName, $validOwners, $expected)
      *
      * @see testLastOwnerIn() For the array format.
      *
-     * @return array
+     * @return array<string, array<int|string|array<int|string>|false>>
      */
     public static function dataLastOwnerIn()
     {

diff --git a/Tests/Utils/PassedParameters/GetParameterFromStackTest.php b/Tests/Utils/PassedParameters/GetParameterFromStackTest.php
@@ -202,10 +202,11 @@ public static function dataGetParameterFunctionCallWithParamName()
      *
      * @dataProvider dataGetParameterFromStack
      *
-     * @param string      $testMarker       The comment which prefaces the target token in the test file.
-     * @param array       $expectedName     The expected result array for the $name parameter.
-     * @param array|false $expectedExpires  The expected result array for the $expires_or_options parameter.
-     * @param array|false $expectedHttpOnly The expected result array for the $httponly parameter.
+     * @param string                          $testMarker       The comment which prefaces the target token in the test file.
+     * @param array<string, int|string>|false $expectedName     The expected result array for the $name parameter.
+     * @param array<string, int|string>|false $expectedExpires  The expected result array for the $expires_or_options
+     *                                                          parameter.
+     * @param array<string, int|string>|false $expectedHttpOnly The expected result array for the $httponly parameter.
      *
      * @return void
      */
@@ -280,7 +281,7 @@ public function testGetParameterFromStack($testMarker, $expectedName, $expectedE
      *
      * @see testGetParameterFromStack() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, string|array<string, int|string>|false>>
      */
     public static function dataGetParameterFromStack()
     {
@@ -413,9 +414,9 @@ public static function dataGetParameterFromStack()
      *
      * @dataProvider dataGetParameterFromStackNamedAfterVariadic
      *
-     * @param int         $offset   The positional offfset to pass.
-     * @param array       $names    The parameter names to pass.
-     * @param array|false $expected The expected result array for the parameter.
+     * @param int                             $offset   The positional offfset to pass.
+     * @param array<string>                   $names    The parameter names to pass.
+     * @param array<string, int|string>|false $expected The expected result array for the parameter.
      *
      * @return void
      */
@@ -446,7 +447,7 @@ public function testGetParameterFromStackNamedAfterVariadic($offset, $names, $ex
      *
      * @see testGetParameterFromStackNamedAfterVariadic() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, int|array<string>|array<string, int|string>|false>>
      */
     public static function dataGetParameterFromStackNamedAfterVariadic()
     {

diff --git a/Tests/Utils/PassedParameters/GetParametersNamedTest.php b/Tests/Utils/PassedParameters/GetParametersNamedTest.php
@@ -33,10 +33,11 @@ final class GetParametersNamedTest extends UtilityMethodTestCase
      *
      * @dataProvider dataGetParameters
      *
-     * @param string     $testMarker    The comment which prefaces the target token in the test file.
-     * @param int|string $targetType    The type of token to look for.
-     * @param array      $expected      The expected parameter array.
-     * @param mixed      $targetContent Optional. The token content to look for.
+     * @param string                                       $testMarker    The comment which prefaces the target token
+     *                                                                    in the test file.
+     * @param int|string                                   $targetType    The type of token to look for.
+     * @param array<int|string, array<string, int|string>> $expected      The expected parameter array.
+     * @param string|null                                  $targetContent Optional. The token content to look for.
      *
      * @return void
      */
@@ -73,7 +74,7 @@ public function testGetParameters($testMarker, $targetType, $expected, $targetCo
      *
      * @see testGetParameters() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, int|string|array<int|string, array<string, int|string>>|null>>
      */
     public static function dataGetParameters()
     {

diff --git a/Tests/Utils/PassedParameters/GetParametersSkipShortArrayCheckTest.php b/Tests/Utils/PassedParameters/GetParametersSkipShortArrayCheckTest.php
@@ -60,7 +60,7 @@ public function testHasParametersDontSkipShortArrayCheck($testMarker, $targetTyp
      *
      * @see testHasParametersDontSkipShortArrayCheck() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, int|string|bool|array<int, array<string, int|string>>>>
      */
     public static function dataHasParametersDontSkipShortArrayCheck()
     {
@@ -79,9 +79,9 @@ public static function dataHasParametersDontSkipShortArrayCheck()
      *
      * @dataProvider dataGetParametersSkipShortArrayCheck
      *
-     * @param string     $testMarker The comment which prefaces the target token in the test file.
-     * @param int|string $targetType The type of token to look for.
-     * @param array      $expected   The expected return value.
+     * @param string                                $testMarker The comment which prefaces the target token in the test file.
+     * @param int|string                            $targetType The type of token to look for.
+     * @param array<int, array<string, int|string>> $expected   The expected return value.
      *
      * @return void
      */
@@ -124,7 +124,7 @@ public function testGetParametersSkipShortArrayCheck($testMarker, $targetType, $
      *
      * @see testGetParametersSkipShortArrayCheck() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, int|string|bool|array<int, array<string, int|string>>>>
      */
     public static function dataGetParametersSkipShortArrayCheck()
     {
@@ -143,7 +143,7 @@ public static function dataGetParametersSkipShortArrayCheck()
      * @see testGetParametersSkipShortArrayCheck()     For the array format.
      * @see testHasParametersDontSkipShortArrayCheck() For the array format.
      *
-     * @return array
+     * @return array<string, array<string, int|string|bool|array<int, array<string, int|string>>>>
      */
     public static function dataTestCases()
     {