Various minor doc fixes

jrfnl · jrfnl · commit c07b4cc5c6f6 · 2024-05-06T05:27:01.000+02:00
... picked up along the way.
diff --git a/autoload.php b/autoload.php
@@ -298,7 +298,7 @@ public static function getLoadedClassName($path)
          *
          * @param string $class The name of the class.
          *
-         * @throws \Exception If the class name has not been loaded
+         * @throws \Exception If the class name has not been loaded.
          * @return string
          */
         public static function getLoadedFileName($class)
diff --git a/src/Fixer.php b/src/Fixer.php
@@ -228,7 +228,7 @@ public function fixFile()
      *
      * @return string
      *
-     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException when the diff command fails.
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException When the diff command fails.
      */
     public function generateDiff($filePath=null, $colors=true)
     {
diff --git a/src/Standards/Generic/Sniffs/CodeAnalysis/JumbledIncrementerSniff.php b/src/Standards/Generic/Sniffs/CodeAnalysis/JumbledIncrementerSniff.php
@@ -101,7 +101,7 @@ public function process(File $phpcsFile, $stackPtr)
      * Get all used variables in the incrementer part of a for statement.
      *
      * @param array<int, array>    $tokens Array with all code sniffer tokens.
-     * @param array<string, mixed> $token  Current for loop token
+     * @param array<string, mixed> $token  Current for loop token.
      *
      * @return string[] List of all found incrementer variables.
      */
diff --git a/src/Standards/Generic/Sniffs/Debug/ClosureLinterSniff.php b/src/Standards/Generic/Sniffs/Debug/ClosureLinterSniff.php
@@ -63,7 +63,7 @@ public function register()
      *                                               the token was found.
      *
      * @return int
-     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jslint.js could not be run
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jslint.js could not be run.
      */
     public function process(File $phpcsFile, $stackPtr)
     {
diff --git a/src/Standards/Generic/Sniffs/Debug/ESLintSniff.php b/src/Standards/Generic/Sniffs/Debug/ESLintSniff.php
@@ -54,7 +54,7 @@ public function register()
      *                                               the token was found.
      *
      * @return int
-     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jshint.js could not be run
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jshint.js could not be run.
      */
     public function process(File $phpcsFile, $stackPtr)
     {
diff --git a/src/Standards/Generic/Sniffs/Debug/JSHintSniff.php b/src/Standards/Generic/Sniffs/Debug/JSHintSniff.php
@@ -48,7 +48,7 @@ public function register()
      *                                               the token was found.
      *
      * @return int
-     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jshint.js could not be run
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jshint.js could not be run.
      */
     public function process(File $phpcsFile, $stackPtr)
     {
diff --git a/src/Standards/Squiz/Sniffs/Classes/SelfMemberReferenceSniff.php b/src/Standards/Squiz/Sniffs/Classes/SelfMemberReferenceSniff.php
@@ -182,7 +182,7 @@ protected function processTokenOutsideScope(File $phpcsFile, $stackPtr)
     /**
      * Returns the declaration names for classes/interfaces/functions with a namespace.
      *
-     * @param array $tokens   Token stack for this file
+     * @param array $tokens   Token stack for this file.
      * @param int   $stackPtr The position where the namespace building will start.
      *
      * @return string
diff --git a/src/Standards/Squiz/Sniffs/Debug/JSLintSniff.php b/src/Standards/Squiz/Sniffs/Debug/JSLintSniff.php
@@ -47,7 +47,7 @@ public function register()
      *                                               the token was found.
      *
      * @return int
-     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jslint.js could not be run
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jslint.js could not be run.
      */
     public function process(File $phpcsFile, $stackPtr)
     {
diff --git a/src/Tokenizers/CSS.php b/src/Tokenizers/CSS.php
@@ -22,7 +22,7 @@ class CSS extends PHP
      *
      * Pre-checks the content to see if it looks minified.
      *
-     * @param string                  $content The content to tokenize,
+     * @param string                  $content The content to tokenize.
      * @param \PHP_CodeSniffer\Config $config  The config data for the run.
      * @param string                  $eolChar The EOL char used in the content.
      *
diff --git a/src/Tokenizers/JS.php b/src/Tokenizers/JS.php
@@ -251,7 +251,7 @@ class JS extends Tokenizer
      *
      * Pre-checks the content to see if it looks minified.
      *
-     * @param string                  $content The content to tokenize,
+     * @param string                  $content The content to tokenize.
      * @param \PHP_CodeSniffer\Config $config  The config data for the run.
      * @param string                  $eolChar The EOL char used in the content.
      *
diff --git a/src/Tokenizers/PHP.php b/src/Tokenizers/PHP.php
@@ -3712,10 +3712,10 @@ public static function resolveSimpleToken($token)
      * Finds a "closer" token (closing parenthesis or square bracket for example)
      * Handle parenthesis balancing while searching for closing token
      *
-     * @param array           $tokens       The list of tokens to iterate searching the closing token (as returned by token_get_all)
-     * @param int             $start        The starting position
-     * @param string|string[] $openerTokens The opening character
-     * @param string          $closerChar   The closing character
+     * @param array           $tokens       The list of tokens to iterate searching the closing token (as returned by token_get_all).
+     * @param int             $start        The starting position.
+     * @param string|string[] $openerTokens The opening character.
+     * @param string          $closerChar   The closing character.
      *
      * @return int|null The position of the closing token, if found. NULL otherwise.
      */
@@ -3749,8 +3749,8 @@ private function findCloser(array &$tokens, $start, $openerTokens, $closerChar)
      * PHP 8 attributes parser for PHP < 8
      * Handles single-line and multiline attributes.
      *
-     * @param array $tokens   The original array of tokens (as returned by token_get_all)
-     * @param int   $stackPtr The current position in token array
+     * @param array $tokens   The original array of tokens (as returned by token_get_all).
+     * @param int   $stackPtr The current position in token array.
      *
      * @return array|null The array of parsed attribute tokens
      */
diff --git a/src/Tokenizers/Tokenizer.php b/src/Tokenizers/Tokenizer.php
@@ -76,7 +76,7 @@ abstract class Tokenizer
     /**
      * Initialise and run the tokenizer.
      *
-     * @param string                         $content The content to tokenize,
+     * @param string                         $content The content to tokenize.
      * @param \PHP_CodeSniffer\Config | null $config  The config data for the run.
      * @param string                         $eolChar The EOL char used in the content.
      *
diff --git a/tests/Core/Tokenizer/BackfillExplicitOctalNotationTest.php b/tests/Core/Tokenizer/BackfillExplicitOctalNotationTest.php
@@ -17,7 +17,7 @@ final class BackfillExplicitOctalNotationTest extends AbstractTokenizerTestCase
      * Test that explicitly-defined octal values are tokenized as a single number and not as a number and a string.
      *
      * @param string     $marker      The comment which prefaces the target token in the test file.
-     * @param string     $value       The expected content of the token
+     * @param string     $value       The expected content of the token.
      * @param int|string $nextToken   The expected next token.
      * @param string     $nextContent The expected content of the next token.
      *
diff --git a/tests/Core/Tokenizer/TypedConstantsTest.php b/tests/Core/Tokenizer/TypedConstantsTest.php
@@ -109,8 +109,8 @@ public static function dataUntypedConstant()
     /**
      * Test the tokens in the type of a typed constant as well as the constant name are tokenized correctly.
      *
-     * @param string $testMarker The comment prefacing the target token.
-     * @param string $sequence   The expected token sequence.
+     * @param string            $testMarker The comment prefacing the target token.
+     * @param array<int|string> $sequence   The expected token sequence.
      *
      * @dataProvider dataTypedConstant
      * @dataProvider dataNullableTypedConstant
@@ -151,7 +151,7 @@ public function testTypedConstant($testMarker, array $sequence)
      *
      * @see testTypedConstant()
      *
-     * @return array<string, array<string, string>>
+     * @return array<string, array<string, string|array<int|string>>>
      */
     public static function dataTypedConstant()
     {
diff --git a/tests/Core/Util/HelpTest.php b/tests/Core/Util/HelpTest.php
@@ -462,7 +462,7 @@ public function testReportWidthCalculations($reportWidth, $longOptions, $expecte
     /**
      * Data provider.
      *
-     * @return array<string, array<string, int|string>>
+     * @return array<string, array<string, int|string|array<string>>>
      */
     public static function dataReportWidthCalculations()
     {
@@ -584,8 +584,8 @@ public static function dataColorizeVariableInput()
     /**
      * Test the various option types within a category get displayed correctly.
      *
-     * @param array<string, array<string, string> $input         The options to print.
-     * @param array<string, string>               $expectedRegex Regexes to validate expected output.
+     * @param array<string, array<string, string>> $input         The options to print.
+     * @param array<string, string>                $expectedRegex Regexes to validate expected output.
      *
      * @dataProvider dataPrintCategoryOptions
      *
@@ -619,8 +619,8 @@ public function testPrintCategoryOptionsNoColor($input, $expectedRegex)
     /**
      * Test the various option types within a category get displayed correctly.
      *
-     * @param array<string, array<string, string> $input         The options to print.
-     * @param array<string, string>               $expectedRegex Regexes to validate expected output.
+     * @param array<string, array<string, string>> $input         The options to print.
+     * @param array<string, string>                $expectedRegex Regexes to validate expected output.
      *
      * @dataProvider dataPrintCategoryOptions
      *
diff --git a/tests/Core/Util/SuggestTypeTest.php b/tests/Core/Util/SuggestTypeTest.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Tests for the \PHP_CodeSniffer\Util\Sniffs\Comments::suggestType() method.
+ * Tests for the \PHP_CodeSniffer\Util\Sniffs\Common::suggestType() method.
  *
  * @author    Juliette Reinders Folmer <phpcs_nospam@adviesenzo.nl>
  * @copyright 2019 Juliette Reinders Folmer. All rights reserved.
@@ -13,7 +13,7 @@
 use PHPUnit\Framework\TestCase;
 
 /**
- * Tests for the \PHP_CodeSniffer\Util\Sniffs\Comments::suggestType() method.
+ * Tests for the \PHP_CodeSniffer\Util\Sniffs\Common::suggestType() method.
  *
  * @covers \PHP_CodeSniffer\Util\Common::suggestType
  */
diff --git a/tests/TestSuite7.php b/tests/TestSuite7.php
@@ -19,7 +19,7 @@ class TestSuite extends PHPUnit_TestSuite
     /**
      * Runs the tests and collects their result in a TestResult.
      *
-     * @param \PHPUnit\Framework\TestResult $result A test result.
+     * @param \PHPUnit\Framework\TestResult|null $result A test result.
      *
      * @return \PHPUnit\Framework\TestResult
      */

Original file line number	Diff line number	Diff line change
`@@ -298,7 +298,7 @@ public static function getLoadedClassName($path)`
`298`	`298`	`*`
`299`	`299`	`* @param string $class The name of the class.`
`300`	`300`	`*`
`301`		`- * @throws \Exception If the class name has not been loaded`
	`301`	`+ * @throws \Exception If the class name has not been loaded.`
`302`	`302`	`* @return string`
`303`	`303`	`*/`
`304`	`304`	`public static function getLoadedFileName($class)`
Original file line number	Diff line number	Diff line change
`@@ -228,7 +228,7 @@ public function fixFile()`
`228`	`228`	`*`
`229`	`229`	`* @return string`
`230`	`230`	`*`
`231`		`- * @throws \PHP_CodeSniffer\Exceptions\RuntimeException when the diff command fails.`
	`231`	`+ * @throws \PHP_CodeSniffer\Exceptions\RuntimeException When the diff command fails.`
`232`	`232`	`*/`
`233`	`233`	`public function generateDiff($filePath=null, $colors=true)`
`234`	`234`	`{`
Original file line number	Diff line number	Diff line change
`@@ -101,7 +101,7 @@ public function process(File $phpcsFile, $stackPtr)`
`101`	`101`	`* Get all used variables in the incrementer part of a for statement.`
`102`	`102`	`*`
`103`	`103`	`* @param array<int, array> $tokens Array with all code sniffer tokens.`
`104`		`- * @param array<string, mixed> $token Current for loop token`
	`104`	`+ * @param array<string, mixed> $token Current for loop token.`
`105`	`105`	`*`
`106`	`106`	`* @return string[] List of all found incrementer variables.`
`107`	`107`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -63,7 +63,7 @@ public function register()`
`63`	`63`	`* the token was found.`
`64`	`64`	`*`
`65`	`65`	`* @return int`
`66`		`- * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jslint.js could not be run`
	`66`	`+ * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jslint.js could not be run.`
`67`	`67`	`*/`
`68`	`68`	`public function process(File $phpcsFile, $stackPtr)`
`69`	`69`	`{`
Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@ public function register()`
`54`	`54`	`* the token was found.`
`55`	`55`	`*`
`56`	`56`	`* @return int`
`57`		`- * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jshint.js could not be run`
	`57`	`+ * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jshint.js could not be run.`
`58`	`58`	`*/`
`59`	`59`	`public function process(File $phpcsFile, $stackPtr)`
`60`	`60`	`{`
Original file line number	Diff line number	Diff line change
`@@ -48,7 +48,7 @@ public function register()`
`48`	`48`	`* the token was found.`
`49`	`49`	`*`
`50`	`50`	`* @return int`
`51`		`- * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jshint.js could not be run`
	`51`	`+ * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jshint.js could not be run.`
`52`	`52`	`*/`
`53`	`53`	`public function process(File $phpcsFile, $stackPtr)`
`54`	`54`	`{`
Original file line number	Diff line number	Diff line change
`@@ -182,7 +182,7 @@ protected function processTokenOutsideScope(File $phpcsFile, $stackPtr)`
`182`	`182`	`/**`
`183`	`183`	`* Returns the declaration names for classes/interfaces/functions with a namespace.`
`184`	`184`	`*`
`185`		`- * @param array $tokens Token stack for this file`
	`185`	`+ * @param array $tokens Token stack for this file.`
`186`	`186`	`* @param int $stackPtr The position where the namespace building will start.`
`187`	`187`	`*`
`188`	`188`	`* @return string`
Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,7 @@ public function register()`
`47`	`47`	`* the token was found.`
`48`	`48`	`*`
`49`	`49`	`* @return int`
`50`		`- * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jslint.js could not be run`
	`50`	`+ * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If jslint.js could not be run.`
`51`	`51`	`*/`
`52`	`52`	`public function process(File $phpcsFile, $stackPtr)`
`53`	`53`	`{`
Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@ class CSS extends PHP`
`22`	`22`	`*`
`23`	`23`	`* Pre-checks the content to see if it looks minified.`
`24`	`24`	`*`
`25`		`- * @param string $content The content to tokenize,`
	`25`	`+ * @param string $content The content to tokenize.`
`26`	`26`	`* @param \PHP_CodeSniffer\Config $config The config data for the run.`
`27`	`27`	`* @param string $eolChar The EOL char used in the content.`
`28`	`28`	`*`
Original file line number	Diff line number	Diff line change
`@@ -251,7 +251,7 @@ class JS extends Tokenizer`
`251`	`251`	`*`
`252`	`252`	`* Pre-checks the content to see if it looks minified.`
`253`	`253`	`*`
`254`		`- * @param string $content The content to tokenize,`
	`254`	`+ * @param string $content The content to tokenize.`
`255`	`255`	`* @param \PHP_CodeSniffer\Config $config The config data for the run.`
`256`	`256`	`* @param string $eolChar The EOL char used in the content.`
`257`	`257`	`*`