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

jrfnl · web-flow · commit 675e39984901 · 2020-06-13T19:36:21.000+02:00
Docs: various small fixes
diff --git a/PHPCSUtils/BackCompat/Helper.php b/PHPCSUtils/BackCompat/Helper.php
@@ -172,7 +172,7 @@ public static function getTabWidth(File $phpcsFile)
      *
      * @since 1.0.0
      *
-     * @param \PHP_CodeSniffer\Files\File $phpcsFile Optional. The current file being processed.
+     * @param \PHP_CodeSniffer\Files\File|null $phpcsFile Optional. The current file being processed.
      *
      * @return string Encoding. Defaults to the PHPCS native default, which is 'utf-8'
      *                for PHPCS 3.x and was 'iso-8859-1' for PHPCS 2.x.
@@ -213,8 +213,7 @@ public static function getEncoding(File $phpcsFile = null)
      *
      * @since 1.0.0
      *
-     * @param \PHP_CodeSniffer\Files\File $phpcsFile Optional. The current file
-     *                                               being processed.
+     * @param \PHP_CodeSniffer\Files\File|null $phpcsFile Optional. The current file being processed.
      *
      * @return bool True if annotations should be ignored, false otherwise.
      */
diff --git a/PHPCSUtils/Tokens/Collections.php b/PHPCSUtils/Tokens/Collections.php
@@ -343,7 +343,7 @@ class Collections
      * It is recommended to use the method instead of the property if a standard supports PHPCS < 3.3.0.
      *
      * @see \PHPCSUtils\Tokens\Collections::parameterTypeTokensBC() Related method (cross-version).
-
+     *
      * @since 1.0.0
      *
      * @var array <int|string> => <int|string>
@@ -406,7 +406,7 @@ class Collections
      * The method supports PHPCS 2.6.0 and up.
      *
      * Notable differences:
-     * - The method will include the `T_ARRAY_HINT` and the `T_RETURN_TYPE tokens when used with PHPCS 2.x and 3.x.
+     * - The method will include the `T_ARRAY_HINT` and the `T_RETURN_TYPE` tokens when used with PHPCS 2.x and 3.x.
      *   These token constants will no longer exist in PHPCS 4.x.
      * - The method will include the `T_ARRAY` token which is needed for select arrow functions in PHPCS < 3.5.4.
      *
@@ -580,7 +580,7 @@ public static function functionDeclarationTokens()
      * It is recommended to use the method instead of the property if a standard supports PHPCS < 3.3.0.
      *
      * @see \PHPCSUtils\Tokens\Collections::functionDeclarationTokens() Related method (PHPCS 3.5.3+).
-     * @see \PHPCSUtils\Tokens\FunctionDeclarations::isArrowFunction()  Arrow function verification.
+     * @see \PHPCSUtils\Utils\FunctionDeclarations::isArrowFunction()   Arrow function verification.
      *
      * @since 1.0.0
      *
@@ -661,7 +661,7 @@ public static function propertyTypeTokensBC()
      * The method supports PHPCS 2.6.0 and up.
      *
      * Notable differences:
-     * - The method will include the `T_ARRAY_HINT` and the `T_RETURN_TYPE tokens when used with PHPCS 2.x and 3.x.
+     * - The method will include the `T_ARRAY_HINT` and the `T_RETURN_TYPE` tokens when used with PHPCS 2.x and 3.x.
      *   These token constants will no longer exist in PHPCS 4.x.
      * - The method will include the `T_ARRAY` token which is needed for select arrow functions in PHPCS < 3.5.4.
      *
diff --git a/PHPCSUtils/Utils/Arrays.php b/PHPCSUtils/Utils/Arrays.php
@@ -288,6 +288,7 @@ public static function getDoubleArrowPtr(File $phpcsFile, $start, $end)
 
             /*
              * BC: work-around a bug in PHPCS 3.5.4 where the double arrow is incorrectly tokenized as T_STRING.
+             *
              * @link https://github.com/squizlabs/PHP_CodeSniffer/issues/2865
              */
             if ($tokens[$doubleArrow]['code'] === \T_STRING && $tokens[$doubleArrow]['content'] === '=>') {
diff --git a/PHPCSUtils/Utils/ControlStructures.php b/PHPCSUtils/Utils/ControlStructures.php
@@ -200,7 +200,7 @@ public static function isElseIf(File $phpcsFile, $stackPtr)
      * Get the scope opener and closer for a `declare` statement.
      *
      * A `declare` statement can be:
-     * - applied to the rest of the file, like `declare(ticks=1);`;
+     * - applied to the rest of the file, like `declare(ticks=1);`
      * - applied to a limited scope using curly braces;
      * - applied to a limited scope using the alternative control structure syntax.
      *
@@ -358,7 +358,7 @@ public static function getDeclareScopeOpenClose(File $phpcsFile, $stackPtr)
      * @return array
      *
      * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified $stackPtr is not of
-     *                                                      type T_CATCH or doesn't exist or in case
+     *                                                      type T_CATCH, doesn't exist or in case
      *                                                      of a parse error.
      */
     public static function getCaughtExceptions(File $phpcsFile, $stackPtr)
diff --git a/PHPCSUtils/Utils/FunctionDeclarations.php b/PHPCSUtils/Utils/FunctionDeclarations.php
@@ -201,7 +201,7 @@ public static function getName(File $phpcsFile, $stackPtr)
      * @return array
      *
      * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified position is not a T_FUNCTION
-     *                                                      or T_CLOSURE token nor an arrow function.
+     *                                                      or T_CLOSURE token, nor an arrow function.
      */
     public static function getProperties(File $phpcsFile, $stackPtr)
     {
@@ -604,7 +604,7 @@ public static function getParameters(File $phpcsFile, $stackPtr)
      *                                               T_STRING token as those are the only two
      *                                               tokens which can be the arrow function keyword.
      *
-     * @return bool TRUE is the token is the "fn" keyword for an arrow function. FALSE when not or
+     * @return bool TRUE if the token is the "fn" keyword for an arrow function. FALSE when not or
      *              in case of live coding/parse error.
      */
     public static function isArrowFunction(File $phpcsFile, $stackPtr)
diff --git a/PHPCSUtils/Utils/Lists.php b/PHPCSUtils/Utils/Lists.php
@@ -260,7 +260,7 @@ public static function getOpenClose(File $phpcsFile, $stackPtr, $isShortList = n
      *                                                 // second item in `list($a, , $b)`.
      *         'is_nested_list'       => bool,         // Whether this is a nested list.
      *         'variable'             => string|false, // The base variable being assigned to or
-     *                                                 // FALSE in case of a nested list or avariable variable.
+     *                                                 // FALSE in case of a nested list or a variable variable.
      *                                                 // I.e. `$a` in `list($a['key'])`.
      *         'assignment_token'     => int|false,    // The start pointer for the assignment.
      *         'assignment_end_token' => int|false,    // The end pointer for the assignment.
@@ -269,7 +269,6 @@ public static function getOpenClose(File $phpcsFile, $stackPtr, $isShortList = n
      *                                                 // FALSE when not a reference assignment.
      * </code>
      *
-     *
      * Assignments with keys will have the following additional array indexes set:
      * <code>
      *         'key'                 => string, // The content of the key, cleaned of comments.
diff --git a/PHPCSUtils/Utils/Numbers.php b/PHPCSUtils/Utils/Numbers.php
@@ -95,7 +95,7 @@ class Numbers
         `ixD';
 
     /**
-     * Regex to determine is a T_STRING following a T_[DL]NUMBER is part of a numeric literal sequence.
+     * Regex to determine if a T_STRING following a T_[DL]NUMBER is part of a numeric literal sequence.
      *
      * PHP cross-version compat for PHP 7.4 numeric literals with underscore separators.
      *
@@ -144,7 +144,7 @@ class Numbers
      * Helper function to deal with numeric literals, potentially with underscore separators.
      *
      * PHP < 7.4 does not tokenize numeric literals containing underscores correctly.
-     * As of PHPCS 3.5.3, PHPCS contains a back-fill, but this backfill was buggy in the initial
+     * As of PHPCS 3.5.3, PHPCS contains a backfill, but this backfill was buggy in the initial
      * implementation. A fix for this broken backfill is included in PHPCS 3.5.4.
      *
      * Either way, this function provides a backfill for all PHPCS/PHP combinations where
diff --git a/PHPCSUtils/Utils/ObjectDeclarations.php b/PHPCSUtils/Utils/ObjectDeclarations.php
@@ -219,7 +219,7 @@ public static function getClassProperties(File $phpcsFile, $stackPtr)
      * Works for classes, anonymous classes and interfaces, though it is strongly recommended
      * to use the {@see \PHPCSUtils\Utils\ObjectDeclarations::findExtendedInterfaceNames()}
      * method to examine interfaces instead. Interfaces can extend multiple parent interfaces,
-     * and that use case is not handled by this method.
+     * and that use-case is not handled by this method.
      *
      * Main differences with the PHPCS version:
      * - Bugs fixed:
diff --git a/Tests/BackCompat/BCFile/FindEndOfStatementTest.php b/Tests/BackCompat/BCFile/FindEndOfStatementTest.php
@@ -15,7 +15,7 @@
  *
  * With documentation contributions from:
  * @author    Phil Davis <phil@jankaritech.com>
-
+ *
  * @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
  * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
  */
diff --git a/phpcsutils-autoload.php b/phpcsutils-autoload.php
@@ -102,7 +102,7 @@ class_alias('\PHP_CodeSniffer_Exception', '\PHP_CodeSniffer\Exceptions\Tokenizer
     /*
      * Alias the PHPUnit 4/5 TestCase class to its PHPUnit 6+ name.
      *
-     * This allows the both the PHPCSUtils native unit tests as well as the
+     * This allows both the PHPCSUtils native unit tests as well as the
      * `UtilityMethodTestCase` class to work cross-version with PHPUnit
      * below 6.x and above.
      *

Original file line number	Diff line number	Diff line change
`@@ -172,7 +172,7 @@ public static function getTabWidth(File $phpcsFile)`
`172`	`172`	`*`
`173`	`173`	`* @since 1.0.0`
`174`	`174`	`*`
`175`		`- * @param \PHP_CodeSniffer\Files\File $phpcsFile Optional. The current file being processed.`
	`175`	`+ * @param \PHP_CodeSniffer\Files\File\|null $phpcsFile Optional. The current file being processed.`
`176`	`176`	`*`
`177`	`177`	`* @return string Encoding. Defaults to the PHPCS native default, which is 'utf-8'`
`178`	`178`	`* for PHPCS 3.x and was 'iso-8859-1' for PHPCS 2.x.`
`@@ -213,8 +213,7 @@ public static function getEncoding(File $phpcsFile = null)`
`213`	`213`	`*`
`214`	`214`	`* @since 1.0.0`
`215`	`215`	`*`
`216`		`- * @param \PHP_CodeSniffer\Files\File $phpcsFile Optional. The current file`
`217`		`- * being processed.`
	`216`	`+ * @param \PHP_CodeSniffer\Files\File\|null $phpcsFile Optional. The current file being processed.`
`218`	`217`	`*`
`219`	`218`	`* @return bool True if annotations should be ignored, false otherwise.`
`220`	`219`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -343,7 +343,7 @@ class Collections`
`343`	`343`	`* It is recommended to use the method instead of the property if a standard supports PHPCS < 3.3.0.`
`344`	`344`	`*`
`345`	`345`	`* @see \PHPCSUtils\Tokens\Collections::parameterTypeTokensBC() Related method (cross-version).`
`346`		`-`
	`346`	`+ *`
`347`	`347`	`* @since 1.0.0`
`348`	`348`	`*`
`349`	`349`	`* @var array <int\|string> => <int\|string>`
`@@ -406,7 +406,7 @@ class Collections`
`406`	`406`	`* The method supports PHPCS 2.6.0 and up.`
`407`	`407`	`*`
`408`	`408`	`* Notable differences:`
`409`		- * - The method will include the `T_ARRAY_HINT` and the `T_RETURN_TYPE tokens when used with PHPCS 2.x and 3.x.
	`409`	+ * - The method will include the `T_ARRAY_HINT` and the `T_RETURN_TYPE` tokens when used with PHPCS 2.x and 3.x.
`410`	`410`	`* These token constants will no longer exist in PHPCS 4.x.`
`411`	`411`	* - The method will include the `T_ARRAY` token which is needed for select arrow functions in PHPCS < 3.5.4.
`412`	`412`	`*`
`@@ -580,7 +580,7 @@ public static function functionDeclarationTokens()`
`580`	`580`	`* It is recommended to use the method instead of the property if a standard supports PHPCS < 3.3.0.`
`581`	`581`	`*`
`582`	`582`	`* @see \PHPCSUtils\Tokens\Collections::functionDeclarationTokens() Related method (PHPCS 3.5.3+).`
`583`		`- * @see \PHPCSUtils\Tokens\FunctionDeclarations::isArrowFunction() Arrow function verification.`
	`583`	`+ * @see \PHPCSUtils\Utils\FunctionDeclarations::isArrowFunction() Arrow function verification.`
`584`	`584`	`*`
`585`	`585`	`* @since 1.0.0`
`586`	`586`	`*`
`@@ -661,7 +661,7 @@ public static function propertyTypeTokensBC()`
`661`	`661`	`* The method supports PHPCS 2.6.0 and up.`
`662`	`662`	`*`
`663`	`663`	`* Notable differences:`
`664`		- * - The method will include the `T_ARRAY_HINT` and the `T_RETURN_TYPE tokens when used with PHPCS 2.x and 3.x.
	`664`	+ * - The method will include the `T_ARRAY_HINT` and the `T_RETURN_TYPE` tokens when used with PHPCS 2.x and 3.x.
`665`	`665`	`* These token constants will no longer exist in PHPCS 4.x.`
`666`	`666`	* - The method will include the `T_ARRAY` token which is needed for select arrow functions in PHPCS < 3.5.4.
`667`	`667`	`*`
Original file line number	Diff line number	Diff line change
`@@ -200,7 +200,7 @@ public static function isElseIf(File $phpcsFile, $stackPtr)`
`200`	`200`	* Get the scope opener and closer for a `declare` statement.
`201`	`201`	`*`
`202`	`202`	* A `declare` statement can be:
`203`		- * - applied to the rest of the file, like `declare(ticks=1);`;
	`203`	+ * - applied to the rest of the file, like `declare(ticks=1);`
`204`	`204`	`* - applied to a limited scope using curly braces;`
`205`	`205`	`* - applied to a limited scope using the alternative control structure syntax.`
`206`	`206`	`*`
`@@ -358,7 +358,7 @@ public static function getDeclareScopeOpenClose(File $phpcsFile, $stackPtr)`
`358`	`358`	`* @return array`
`359`	`359`	`*`
`360`	`360`	`* @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified $stackPtr is not of`
`361`		`- * type T_CATCH or doesn't exist or in case`
	`361`	`+ * type T_CATCH, doesn't exist or in case`
`362`	`362`	`* of a parse error.`
`363`	`363`	`*/`
`364`	`364`	`public static function getCaughtExceptions(File $phpcsFile, $stackPtr)`
Original file line number	Diff line number	Diff line change
`@@ -201,7 +201,7 @@ public static function getName(File $phpcsFile, $stackPtr)`
`201`	`201`	`* @return array`
`202`	`202`	`*`
`203`	`203`	`* @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified position is not a T_FUNCTION`
`204`		`- * or T_CLOSURE token nor an arrow function.`
	`204`	`+ * or T_CLOSURE token, nor an arrow function.`
`205`	`205`	`*/`
`206`	`206`	`public static function getProperties(File $phpcsFile, $stackPtr)`
`207`	`207`	`{`
`@@ -604,7 +604,7 @@ public static function getParameters(File $phpcsFile, $stackPtr)`
`604`	`604`	`* T_STRING token as those are the only two`
`605`	`605`	`* tokens which can be the arrow function keyword.`
`606`	`606`	`*`
`607`		`- * @return bool TRUE is the token is the "fn" keyword for an arrow function. FALSE when not or`
	`607`	`+ * @return bool TRUE if the token is the "fn" keyword for an arrow function. FALSE when not or`
`608`	`608`	`* in case of live coding/parse error.`
`609`	`609`	`*/`
`610`	`610`	`public static function isArrowFunction(File $phpcsFile, $stackPtr)`
Original file line number	Diff line number	Diff line change
`@@ -95,7 +95,7 @@ class Numbers`
`95`	`95`	`ixD';
`96`	`96`
`97`	`97`	`/**`
`98`		`- * Regex to determine is a T_STRING following a T_[DL]NUMBER is part of a numeric literal sequence.`
	`98`	`+ * Regex to determine if a T_STRING following a T_[DL]NUMBER is part of a numeric literal sequence.`
`99`	`99`	`*`
`100`	`100`	`* PHP cross-version compat for PHP 7.4 numeric literals with underscore separators.`
`101`	`101`	`*`
`@@ -144,7 +144,7 @@ class Numbers`
`144`	`144`	`* Helper function to deal with numeric literals, potentially with underscore separators.`
`145`	`145`	`*`
`146`	`146`	`* PHP < 7.4 does not tokenize numeric literals containing underscores correctly.`
`147`		`- * As of PHPCS 3.5.3, PHPCS contains a back-fill, but this backfill was buggy in the initial`
	`147`	`+ * As of PHPCS 3.5.3, PHPCS contains a backfill, but this backfill was buggy in the initial`
`148`	`148`	`* implementation. A fix for this broken backfill is included in PHPCS 3.5.4.`
`149`	`149`	`*`
`150`	`150`	`* Either way, this function provides a backfill for all PHPCS/PHP combinations where`
Original file line number	Diff line number	Diff line change
`@@ -219,7 +219,7 @@ public static function getClassProperties(File $phpcsFile, $stackPtr)`
`219`	`219`	`* Works for classes, anonymous classes and interfaces, though it is strongly recommended`
`220`	`220`	`* to use the {@see \PHPCSUtils\Utils\ObjectDeclarations::findExtendedInterfaceNames()}`
`221`	`221`	`* method to examine interfaces instead. Interfaces can extend multiple parent interfaces,`
`222`		`- * and that use case is not handled by this method.`
	`222`	`+ * and that use-case is not handled by this method.`
`223`	`223`	`*`
`224`	`224`	`* Main differences with the PHPCS version:`
`225`	`225`	`* - Bugs fixed:`
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@`
`15`	`15`	`*`
`16`	`16`	`* With documentation contributions from:`
`17`	`17`	`* @author Phil Davis <[email protected]>`
`18`		`-`
	`18`	`+ *`
`19`	`19`	`* @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)`
`20`	`20`	`* @license https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence`
`21`	`21`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -102,7 +102,7 @@ class_alias('\PHP_CodeSniffer_Exception', '\PHP_CodeSniffer\Exceptions\Tokenizer`
`102`	`102`	`/*`
`103`	`103`	`* Alias the PHPUnit 4/5 TestCase class to its PHPUnit 6+ name.`
`104`	`104`	`*`
`105`		`- * This allows the both the PHPCSUtils native unit tests as well as the`
	`105`	`+ * This allows both the PHPCSUtils native unit tests as well as the`
`106`	`106`	* `UtilityMethodTestCase` class to work cross-version with PHPUnit
`107`	`107`	`* below 6.x and above.`
`108`	`108`	`*`