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

Docs: various fixes & improve type specificity
PHPCSStandards · Sep 9, 2024 · fc4f321 · fc4f321
2 parents 77a01e7 + 684db66
commit fc4f321
Show file tree

Hide file tree

Showing 8 changed files with 28 additions and 27 deletions.
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.