Docs: fix various incorrect type annotations

Includes a number of fixes previously pulled in (closed) PR 3703.

Co-authored-by: Andrew Dawes <andrewsdawes@gmail.com>

Author: jrfnl

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/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/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 = [];