Merge pull request #154 from PHPCSStandards/feature/various-docs-fixes

jrfnl · web-flow · commit fc4f3210eb04 · 2024-09-10T01:43:07.000+02:00
Docs: various fixes &amp; improve type specificity
diff --git a/PHPCSDebug/Sniffs/Debug/TokenListSniff.php b/PHPCSDebug/Sniffs/Debug/TokenListSniff.php
@@ -28,7 +28,7 @@ class TokenListSniff implements Sniff
     /**
      * A list of tokenizers this sniff supports.
      *
-     * @var array
+     * @var array<string>
      */
     public $supportedTokenizers = [
         'PHP',
@@ -41,7 +41,7 @@ class TokenListSniff implements Sniff
      *
      * This prevents issues with "undefined index" notices in case of rare tokenizer issues.
      *
-     * @var array
+     * @var array<string, int|string|array<int, int|string>>
      */
     private $tokenDefaults = [
         'type'       => '?',
@@ -57,7 +57,7 @@ class TokenListSniff implements Sniff
     /**
      * Returns an array of tokens this test wants to listen for.
      *
-     * @return array
+     * @return array<int|string>
      */
     public function register()
     {
@@ -74,7 +74,8 @@ public function register()
      * @param int                         $stackPtr  The position of the current
      *                                               token in the stack.
      *
-     * @return void
+     * @return int|void Integer stack pointer to skip forward or void to continue
+     *                  normal file processing.
      */
     public function process(File $phpcsFile, $stackPtr)
     {
diff --git a/PHPCSDebug/Tests/Debug/TokenListCssTest.php b/PHPCSDebug/Tests/Debug/TokenListCssTest.php
@@ -33,7 +33,7 @@ final class TokenListCssTest extends UtilityMethodTestCase
     /**
      * Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).
      *
-     * @var array
+     * @var array<string>
      */
     protected static $selectedSniff = ['PHPCSDebug.Debug.TokenList'];
 
diff --git a/PHPCSDebug/Tests/Debug/TokenListJsTest.php b/PHPCSDebug/Tests/Debug/TokenListJsTest.php
@@ -33,7 +33,7 @@ final class TokenListJsTest extends UtilityMethodTestCase
     /**
      * Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).
      *
-     * @var array
+     * @var array<string>
      */
     protected static $selectedSniff = ['PHPCSDebug.Debug.TokenList'];
 
diff --git a/PHPCSDebug/Tests/Debug/TokenListUnitTest.php b/PHPCSDebug/Tests/Debug/TokenListUnitTest.php
@@ -26,7 +26,7 @@ final class TokenListUnitTest extends UtilityMethodTestCase
     /**
      * Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).
      *
-     * @var array
+     * @var array<string>
      */
     protected static $selectedSniff = ['PHPCSDebug.Debug.TokenList'];
 
diff --git a/Scripts/CheckSniffCompleteness.php b/Scripts/CheckSniffCompleteness.php
@@ -31,7 +31,7 @@ class CheckSniffCompleteness
      * To disable showing progress, pass `--no-progress` on the command line
      * when calling the script.
      *
-     * @var boolean
+     * @var bool
      */
     protected $showProgress = true;
 
@@ -43,7 +43,7 @@ class CheckSniffCompleteness
      * To enable "quiet" mode, pass `-q` on the command line when calling
      * the script.
      *
-     * @var boolean
+     * @var bool
      */
     protected $quietMode = false;
 
@@ -52,7 +52,7 @@ class CheckSniffCompleteness
      *
      * This will be automatically detected if not set from the command-line.
      *
-     * @var boolean
+     * @var bool
      */
     protected $showColored;
 
@@ -66,7 +66,7 @@ class CheckSniffCompleteness
     /**
      * The target directories to examine.
      *
-     * @var array
+     * @var array<string>
      */
     protected $targetDirs = [];
 
@@ -80,7 +80,7 @@ class CheckSniffCompleteness
     /**
      * Directories to exclude from the scan.
      *
-     * @var array
+     * @var array<string>
      */
     protected $excludedDirs = [
         'vendor',
@@ -89,14 +89,14 @@ class CheckSniffCompleteness
     /**
      * List of all files in the repo.
      *
-     * @var array
+     * @var array<string, int> Key is a file name, value irrelevant.
      */
     protected $allFiles = [];
 
     /**
      * List of all sniff files in the repo.
      *
-     * @var array
+     * @var array<string>
      */
     protected $allSniffs = [];
 
@@ -105,7 +105,7 @@ class CheckSniffCompleteness
      *
      * Keys are the strings to search for, values the replacement values.
      *
-     * @var array
+     * @var array<string, string>
      */
     private $sniffToDoc = [
         '/Sniffs/'  => '/Docs/',
@@ -117,7 +117,7 @@ class CheckSniffCompleteness
      *
      * Keys are the strings to search for, values the replacement values.
      *
-     * @var array
+     * @var array<string, string>
      */
     private $sniffToUnitTest = [
         '/Sniffs/' => '/Tests/',
@@ -127,7 +127,7 @@ class CheckSniffCompleteness
     /**
      * Possible test case file extensions.
      *
-     * @var array
+     * @var array<string>
      */
     private $testCaseExtensions = [
         '.inc',
diff --git a/Scripts/FileList.php b/Scripts/FileList.php
@@ -45,9 +45,9 @@ class FileList
     protected $rootPath;
 
     /**
-     * Recursive directory iterator.
+     * Regex iterator.
      *
-     * @var \DirectoryIterator
+     * @var \RegexIterator
      */
     protected $fileIterator;
 
@@ -85,7 +85,7 @@ public function __construct($directory, $rootPath = '', $filter = '')
     /**
      * Retrieve the filtered file list iterator.
      *
-     * @return array
+     * @return \RegexIterator
      */
     public function getIterator()
     {
@@ -95,7 +95,7 @@ public function getIterator()
     /**
      * Retrieve the filtered file list as an array.
      *
-     * @return array
+     * @return array<string>
      */
     public function getList()
     {
diff --git a/Tests/DocsXsd/DocsXsdTest.php b/Tests/DocsXsd/DocsXsdTest.php
@@ -58,7 +58,7 @@ public function testXsdValidationPassedWithValidXml($fixtureFile)
     /**
      * Data provider for valid test cases.
      *
-     * @return array
+     * @return array<string, array<string, string>>
      */
     public function dataValidXsd()
     {
@@ -108,7 +108,7 @@ public function testXsdValidationFailsForInvalidXml($fixtureFile, $expectedStdOu
     /**
      * Data provider for invalid test cases.
      *
-     * @return array
+     * @return array<string, array<string, string>>
      */
     public function dataInvalidXsd()
     {
diff --git a/Tests/IOTestCase.php b/Tests/IOTestCase.php
@@ -28,10 +28,10 @@ abstract class IOTestCase extends XTestCase
      *                                Note: if the command itself already contains a "working directory" argument,
      *                                this parameter will normally not need to be passed.
      *
-     * @return array Format:
-     *               'exitcode' int    The exit code from the command.
-     *               'stdout'   string The output send to stdout.
-     *               'stderr'   string The output send to stderr.
+     * @return array<string, int|string> Format:
+     *                                   'exitcode' int    The exit code from the command.
+     *                                   'stdout'   string The output send to stdout.
+     *                                   'stderr'   string The output send to stderr.
      *
      * @throws \RuntimeException When the passed arguments do not comply.
      * @throws \RuntimeException When no resource could be obtained to execute the command.

Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ class TokenListSniff implements Sniff`
`28`	`28`	`/**`
`29`	`29`	`* A list of tokenizers this sniff supports.`
`30`	`30`	`*`
`31`		`- * @var array`
	`31`	`+ * @var array<string>`
`32`	`32`	`*/`
`33`	`33`	`public $supportedTokenizers = [`
`34`	`34`	`'PHP',`
`@@ -41,7 +41,7 @@ class TokenListSniff implements Sniff`
`41`	`41`	`*`
`42`	`42`	`* This prevents issues with "undefined index" notices in case of rare tokenizer issues.`
`43`	`43`	`*`
`44`		`- * @var array`
	`44`	`+ * @var array<string, int\|string\|array<int, int\|string>>`
`45`	`45`	`*/`
`46`	`46`	`private $tokenDefaults = [`
`47`	`47`	`'type' => '?',`
`@@ -57,7 +57,7 @@ class TokenListSniff implements Sniff`
`57`	`57`	`/**`
`58`	`58`	`* Returns an array of tokens this test wants to listen for.`
`59`	`59`	`*`
`60`		`- * @return array`
	`60`	`+ * @return array<int\|string>`
`61`	`61`	`*/`
`62`	`62`	`public function register()`
`63`	`63`	`{`
`@@ -74,7 +74,8 @@ public function register()`
`74`	`74`	`* @param int $stackPtr The position of the current`
`75`	`75`	`* token in the stack.`
`76`	`76`	`*`
`77`		`- * @return void`
	`77`	`+ * @return int\|void Integer stack pointer to skip forward or void to continue`
	`78`	`+ * normal file processing.`
`78`	`79`	`*/`
`79`	`80`	`public function process(File $phpcsFile, $stackPtr)`
`80`	`81`	`{`
Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@ final class TokenListCssTest extends UtilityMethodTestCase`
`33`	`33`	`/**`
`34`	`34`	`* Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).`
`35`	`35`	`*`
`36`		`- * @var array`
	`36`	`+ * @var array<string>`
`37`	`37`	`*/`
`38`	`38`	`protected static $selectedSniff = ['PHPCSDebug.Debug.TokenList'];`
`39`	`39`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ final class TokenListUnitTest extends UtilityMethodTestCase`
`26`	`26`	`/**`
`27`	`27`	`* Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).`
`28`	`28`	`*`
`29`		`- * @var array`
	`29`	`+ * @var array<string>`
`30`	`30`	`*/`
`31`	`31`	`protected static $selectedSniff = ['PHPCSDebug.Debug.TokenList'];`
`32`	`32`
Original file line number	Diff line number	Diff line change
`@@ -45,9 +45,9 @@ class FileList`
`45`	`45`	`protected $rootPath;`
`46`	`46`
`47`	`47`	`/**`
`48`		`- * Recursive directory iterator.`
	`48`	`+ * Regex iterator.`
`49`	`49`	`*`
`50`		`- * @var \DirectoryIterator`
	`50`	`+ * @var \RegexIterator`
`51`	`51`	`*/`
`52`	`52`	`protected $fileIterator;`
`53`	`53`
`@@ -85,7 +85,7 @@ public function __construct($directory, $rootPath = '', $filter = '')`
`85`	`85`	`/**`
`86`	`86`	`* Retrieve the filtered file list iterator.`
`87`	`87`	`*`
`88`		`- * @return array`
	`88`	`+ * @return \RegexIterator`
`89`	`89`	`*/`
`90`	`90`	`public function getIterator()`
`91`	`91`	`{`
`@@ -95,7 +95,7 @@ public function getIterator()`
`95`	`95`	`/**`
`96`	`96`	`* Retrieve the filtered file list as an array.`
`97`	`97`	`*`
`98`		`- * @return array`
	`98`	`+ * @return array<string>`
`99`	`99`	`*/`
`100`	`100`	`public function getList()`
`101`	`101`	`{`
Original file line number	Diff line number	Diff line change
`@@ -58,7 +58,7 @@ public function testXsdValidationPassedWithValidXml($fixtureFile)`
`58`	`58`	`/**`
`59`	`59`	`* Data provider for valid test cases.`
`60`	`60`	`*`
`61`		`- * @return array`
	`61`	`+ * @return array<string, array<string, string>>`
`62`	`62`	`*/`
`63`	`63`	`public function dataValidXsd()`
`64`	`64`	`{`
`@@ -108,7 +108,7 @@ public function testXsdValidationFailsForInvalidXml($fixtureFile, $expectedStdOu`
`108`	`108`	`/**`
`109`	`109`	`* Data provider for invalid test cases.`
`110`	`110`	`*`
`111`		`- * @return array`
	`111`	`+ * @return array<string, array<string, string>>`
`112`	`112`	`*/`
`113`	`113`	`public function dataInvalidXsd()`
`114`	`114`	`{`