Docs: variety of fixes

CHANGELOG.md

@@ -91,6 +91,8 @@ The file documents changes to the PHP_CodeSniffer project.
     - Thanks to Juliette Reinders Folmer (@jrfnl) for the patch
 - Improved README syntax highlighting
     - Thanks to Benjamin Loison (@Benjamin-Loison) for the patch
+- Various documentation improvements
+    - Thanks to Andrew Dawes (@AndrewDawes) and Juliette Reinders Folmer (@jrfnl) for the patches
 
 ### Removed
 - Removed support for installing via PEAR

src/Config.php

@@ -27,7 +27,7 @@
  *                                     2: ruleset and file parsing output
  *                                     3: sniff execution output
  * @property bool     $interactive     Enable interactive checking mode.
- * @property bool     $parallel        Check files in parallel.
+ * @property int      $parallel        Check files in parallel.
  * @property bool     $cache           Enable the use of the file cache.
  * @property bool     $cacheFile       A file where the cache data should be written
  * @property bool     $colors          Display colours in output.

src/Files/File.php

@@ -755,7 +755,7 @@ public function addErrorOnLine(
 
 
     /**
-     * Records a warning against a specific token in the file.
+     * Records a warning against a specific line in the file.
      *
      * @param string $warning  The error message.
      * @param int    $line     The line on which the warning occurred.

src/Files/FileList.php

@@ -199,7 +199,7 @@ public function current()
     /**
      * Return the file path of the current file being processed.
      *
-     * @return void
+     * @return string|null Path name or `null` when the end of the iterator has been reached.
      */
     #[ReturnTypeWillChange]
     public function key()

src/Fixer.php

@@ -70,7 +70,7 @@ class Fixer
      * If a token is being "fixed" back to its last value, the fix is
      * probably conflicting with another.
      *
-     * @var array<int, string>
+     * @var array<int, array<string, mixed>>
      */
     private $oldTokenValues = [];
 
@@ -349,7 +349,7 @@ public function getTokenContent($stackPtr)
     /**
      * Start recording actions for a changeset.
      *
-     * @return void
+     * @return void|false
      */
     public function beginChangeset()
     {

src/Reports/Hgblame.php

@@ -28,7 +28,7 @@ class Hgblame extends VersionControl
      *
      * @param string $line Line to parse.
      *
-     * @return mixed string or false if impossible to recover.
+     * @return string|false String or FALSE if impossible to recover.
      */
     protected function getAuthor($line)
     {

src/Reports/Info.php

@@ -45,7 +45,7 @@ public function generateFileReport($report, File $phpcsFile, $showSources=false,
 
 
     /**
-     * Prints the source of all errors and warnings.
+     * Prints the recorded metrics.
      *
      * @param string $cachedData    Any partial report data that was returned from
      *                              generateFileReport during the run.

src/Reports/Notifysend.php

@@ -154,7 +154,7 @@ public function generate(
      * @param int      $totalErrors   Total number of errors found during the run.
      * @param int      $totalWarnings Total number of warnings found during the run.
      *
-     * @return string Error message or NULL if no error/warning found.
+     * @return string|null Error message or NULL if no error/warning found.
      */
     protected function generateMessage($checkedFiles, $totalErrors, $totalWarnings)
     {

src/Ruleset.php

@@ -47,7 +47,7 @@ class Ruleset
      * The key is the regular expression and the value is the type
      * of ignore pattern (absolute or relative).
      *
-     * @var array<string, string>
+     * @var array<string, array>
      */
     public $ignorePatterns = [];
 

src/Runner.php

@@ -49,7 +49,7 @@ class Runner
     /**
      * Run the PHPCS script.
      *
-     * @return array
+     * @return int
      */
     public function runPHPCS()
     {
@@ -151,7 +151,7 @@ public function runPHPCS()
     /**
      * Run the PHPCBF script.
      *
-     * @return array
+     * @return int
      */
     public function runPHPCBF()
     {
@@ -595,7 +595,7 @@ private function run()
      * @param string $file    The path of the file that raised the error.
      * @param int    $line    The line number the error was raised at.
      *
-     * @return void
+     * @return bool
      * @throws \PHP_CodeSniffer\Exceptions\RuntimeException
      */
     public function handleErrors($code, $message, $file, $line)

src/Sniffs/AbstractPatternSniff.php

@@ -250,7 +250,7 @@ final public function process(File $phpcsFile, $stackPtr)
      * @param int                         $stackPtr    The position in the tokens stack where
      *                                                 the listening token type was found.
      *
-     * @return array
+     * @return array|false
      */
     protected function processPattern($patternInfo, File $phpcsFile, $stackPtr)
     {
@@ -850,7 +850,7 @@ private function parse($pattern)
      * Creates a skip pattern.
      *
      * @param string $pattern The pattern being parsed.
-     * @param string $from    The token content that the skip pattern starts from.
+     * @param int    $from    The token position that the skip pattern starts from.
      *
      * @return array The pattern step.
      * @see    createTokenPattern()

src/Sniffs/AbstractScopeSniff.php

@@ -42,7 +42,7 @@ abstract class AbstractScopeSniff implements Sniff
     /**
      * The type of scope opener tokens that this test wishes to listen to.
      *
-     * @var string
+     * @var array<int|string>
      */
     private $scopeTokens = [];
 

src/Standards/Generic/Sniffs/Arrays/DisallowShortArraySyntaxSniff.php

@@ -19,7 +19,7 @@ class DisallowShortArraySyntaxSniff implements Sniff
     /**
      * Registers the tokens that this sniff wants to listen for.
      *
-     * @return int[]
+     * @return array<int|string>
      */
     public function register()
     {

src/Standards/Generic/Sniffs/CodeAnalysis/JumbledIncrementerSniff.php

@@ -100,8 +100,8 @@ public function process(File $phpcsFile, $stackPtr)
     /**
      * Get all used variables in the incrementer part of a for statement.
      *
-     * @param array(integer=>array) $tokens Array with all code sniffer tokens.
-     * @param array(string=>mixed)  $token  Current for loop token
+     * @param array<int, array>    $tokens Array with all code sniffer tokens.
+     * @param array<string, mixed> $token  Current for loop token
      *
      * @return string[] List of all found incrementer variables.
      */

src/Standards/Generic/Sniffs/ControlStructures/InlineControlStructureSniff.php

@@ -62,7 +62,7 @@ public function register()
      * @param int                         $stackPtr  The position of the current token in the
      *                                               stack passed in $tokens.
      *
-     * @return void
+     * @return void|int
      */
     public function process(File $phpcsFile, $stackPtr)
     {

src/Standards/Generic/Sniffs/Debug/ClosureLinterSniff.php

@@ -22,14 +22,14 @@ class ClosureLinterSniff implements Sniff
      *
      * All other error codes will show warnings.
      *
-     * @var integer
+     * @var array
      */
     public $errorCodes = [];
 
     /**
      * A list of error codes to ignore.
      *
-     * @var integer
+     * @var array
      */
     public $ignoreCodes = [];
 

src/Standards/Generic/Sniffs/Files/InlineHTMLSniff.php

@@ -48,7 +48,7 @@ public function register()
      * @param int                         $stackPtr  The position of the current token in
      *                                               the stack passed in $tokens.
      *
-     * @return int|null
+     * @return int|void
      */
     public function process(File $phpcsFile, $stackPtr)
     {

src/Standards/Generic/Sniffs/Functions/OpeningFunctionBraceKernighanRitchieSniff.php

@@ -34,7 +34,7 @@ class OpeningFunctionBraceKernighanRitchieSniff implements Sniff
     /**
      * Registers the tokens that this sniff wants to listen for.
      *
-     * @return void
+     * @return array<int|string>
      */
     public function register()
     {

src/Standards/Generic/Sniffs/PHP/DisallowAlternativePHPTagsSniff.php

@@ -28,7 +28,7 @@ class DisallowAlternativePHPTagsSniff implements Sniff
     /**
      * The current PHP version.
      *
-     * @var integer
+     * @var integer|string|null
      */
     private $phpVersion = null;
 

src/Standards/Generic/Sniffs/PHP/DisallowShortOpenTagSniff.php

@@ -46,7 +46,7 @@ public function register()
      * @param int                         $stackPtr  The position of the current token
      *                                               in the stack passed in $tokens.
      *
-     * @return void
+     * @return void|int
      */
     public function process(File $phpcsFile, $stackPtr)
     {

src/Standards/Generic/Sniffs/PHP/LowerCaseConstantSniff.php

@@ -64,7 +64,7 @@ public function register()
      * @param int                         $stackPtr  The position of the current token in the
      *                                               stack passed in $tokens.
      *
-     * @return void
+     * @return void|int
      */
     public function process(File $phpcsFile, $stackPtr)
     {

src/Standards/Generic/Sniffs/PHP/SyntaxSniff.php

@@ -48,7 +48,7 @@ public function register()
      * @param int                         $stackPtr  The position of the current token in
      *                                               the stack passed in $tokens.
      *
-     * @return void
+     * @return int
      */
     public function process(File $phpcsFile, $stackPtr)
     {

src/Standards/Generic/Sniffs/VersionControl/GitMergeConflictSniff.php

@@ -49,7 +49,7 @@ public function register()
      * @param int                         $stackPtr  The position of the current token in the
      *                                               stack passed in $tokens.
      *
-     * @return void
+     * @return int
      */
     public function process(File $phpcsFile, $stackPtr)
     {

src/Standards/Generic/Sniffs/VersionControl/SubversionPropertiesSniff.php

@@ -50,7 +50,7 @@ public function register()
      * @param int                         $stackPtr  The position of the current token
      *                                               in the stack passed in $tokens.
      *
-     * @return void
+     * @return int
      */
     public function process(File $phpcsFile, $stackPtr)
     {
@@ -113,7 +113,7 @@ public function process(File $phpcsFile, $stackPtr)
      *
      * @param string $path The path to return Subversion properties on.
      *
-     * @return array
+     * @return array|null
      * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If Subversion properties file could
      *                                                      not be opened.
      */

src/Standards/Generic/Sniffs/WhiteSpace/ArbitraryParenthesesSpacingSniff.php

@@ -78,7 +78,7 @@ public function register()
      * @param int                         $stackPtr  The position of the current token in
      *                                               the stack passed in $tokens.
      *
-     * @return void
+     * @return void|int
      */
     public function process(File $phpcsFile, $stackPtr)
     {

src/Standards/Generic/Sniffs/WhiteSpace/DisallowSpaceIndentSniff.php

@@ -56,7 +56,7 @@ public function register()
      * @param int                         $stackPtr  The position of the current token in
      *                                               the stack passed in $tokens.
      *
-     * @return void
+     * @return int
      */
     public function process(File $phpcsFile, $stackPtr)
     {

src/Standards/Generic/Sniffs/WhiteSpace/DisallowTabIndentSniff.php

@@ -56,7 +56,7 @@ public function register()
      * @param int                         $stackPtr  The position of the current token in
      *                                               the stack passed in $tokens.
      *
-     * @return void
+     * @return int
      */
     public function process(File $phpcsFile, $stackPtr)
     {

src/Standards/Generic/Sniffs/WhiteSpace/ScopeIndentSniff.php

@@ -80,7 +80,7 @@ class ScopeIndentSniff implements Sniff
      * This is a cached copy of the public version of this var, which
      * can be set in a ruleset file, and some core ignored tokens.
      *
-     * @var int[]
+     * @var array<int|string, bool>
      */
     private $ignoreIndentation = [];
 

src/Standards/Generic/Tests/Debug/CSSLintUnitTest.php

@@ -19,7 +19,7 @@ class CSSLintUnitTest extends AbstractSniffUnitTest
     /**
      * Should this test be skipped for some reason.
      *
-     * @return void
+     * @return bool
      */
     protected function shouldSkipTest()
     {

src/Standards/Generic/Tests/Debug/ClosureLinterUnitTest.php

@@ -19,7 +19,7 @@ class ClosureLinterUnitTest extends AbstractSniffUnitTest
     /**
      * Should this test be skipped for some reason.
      *
-     * @return void
+     * @return bool
      */
     protected function shouldSkipTest()
     {

src/Standards/Generic/Tests/Debug/ESLintUnitTest.php

@@ -68,7 +68,7 @@ protected function resetProperties()
     /**
      * Should this test be skipped for some reason.
      *
-     * @return void
+     * @return bool
      */
     protected function shouldSkipTest()
     {

src/Standards/Generic/Tests/Debug/JSHintUnitTest.php

@@ -19,7 +19,7 @@ class JSHintUnitTest extends AbstractSniffUnitTest
     /**
      * Should this test be skipped for some reason.
      *
-     * @return void
+     * @return bool
      */
     protected function shouldSkipTest()
     {

src/Standards/Generic/Tests/Files/ExecutableFileUnitTest.php

@@ -18,7 +18,7 @@ class ExecutableFileUnitTest extends AbstractSniffUnitTest
     /**
      * Should this test be skipped for some reason.
      *
-     * @return void
+     * @return bool
      */
     protected function shouldSkipTest()
     {

src/Standards/Generic/Tests/VersionControl/SubversionPropertiesUnitTest.php

@@ -18,7 +18,7 @@ class SubversionPropertiesUnitTest extends AbstractSniffUnitTest
     /**
      * Should this test be skipped for some reason.
      *
-     * @return void
+     * @return bool
      */
     protected function shouldSkipTest()
     {

src/Standards/MySource/Sniffs/CSS/BrowserSpecificStylesSniff.php

@@ -43,7 +43,7 @@ class BrowserSpecificStylesSniff implements Sniff
     /**
      * Returns the token types that this sniff is interested in.
      *
-     * @return int[]
+     * @return array<int|string>
      */
     public function register()
     {

src/Standards/MySource/Sniffs/Channels/IncludeOwnSystemSniff.php

@@ -82,7 +82,7 @@ public function process(File $phpcsFile, $stackPtr)
      * @param int                         $stackPtr  The position in the tokens array of the
      *                                               potentially included class.
      *
-     * @return string
+     * @return bool
      */
     protected function getIncludedClassFromToken(
         $phpcsFile,

src/Standards/MySource/Sniffs/Channels/IncludeSystemSniff.php

@@ -19,7 +19,7 @@ class IncludeSystemSniff extends AbstractScopeSniff
     /**
      * A list of classes that don't need to be included.
      *
-     * @var string[]
+     * @var array<string, bool>
      */
     private $ignore = [
         'self'                      => true,
@@ -286,7 +286,7 @@ protected function processTokenOutsideScope(File $phpcsFile, $stackPtr)
      * @param int                         $stackPtr  The position in the tokens array of the
      *                                               potentially included class.
      *
-     * @return string
+     * @return string|false
      */
     protected function getIncludedClassFromToken(File $phpcsFile, array $tokens, $stackPtr)
     {