Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: various minor updates #309

Merged
merged 4 commits into from
Apr 19, 2022
Merged

Docs: various minor updates #309

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0183e01
PassedParameters: improve/simplify documentation about supported cons…
jrfnl Nov 29, 2020
6f5cd4b
Docs: various grammar and punctuation fixes
jrfnl Apr 18, 2022
590bbcb
Docs: update info on PHPCS
jrfnl Apr 18, 2022
a52c3ff
Docs/Collections: various tweaks
jrfnl Apr 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion PHPCSUtils/BackCompat/BCFile.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -573,6 +573,7 @@ public static function getMethodParameters(File $phpcsFile, $stackPtr)
* - PHPCS 3.5.0: The Exception thrown changed from a `\PHP_CodeSniffer\Exceptions\TokenizerException`
* to `\PHP_CodeSniffer\Exceptions\RuntimeException`.
* - PHPCS 3.5.3: Added support for PHP 7.4 `T_FN` arrow functions.
* - PHPCS 3.5.6: Added support for PHP 8.0 `static` return types.
* - PHPCS 3.5.7: Added support for namespace operators in type declarations. PHPCS#3066.
* - PHPCS 3.6.0: Added support for PHP 8.0 union types. PHPCS#3032.
* - PHPCS 3.6.0: Added new `"return_type_end_token"` index. PHPCS#3153.
Expand All @@ -582,7 +583,7 @@ public static function getMethodParameters(File $phpcsFile, $stackPtr)
*
* @since 1.0.0
* @since 1.0.0-alpha2 Added BC support for PHP 7.4 arrow functions.
* @since 1.0.0-alpha3 Added support for PHP 8.0 static return type (expected in future PHPCS release).
* @since 1.0.0-alpha3 Added support for PHP 8.0 static return type.
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
* @param int $stackPtr The position in the stack of the function token to
Expand Down Expand Up @@ -1229,6 +1230,7 @@ public static function getTokensAsString(File $phpcsFile, $start, $length, $orig
* - Introduced in PHPCS 2.1.0.
* - PHPCS 2.6.2: New optional `$ignore` parameter to selectively ignore stop points.
* - PHPCS 3.5.5: Added support for PHP 7.4 `T_FN` arrow functions.
* - PHPCS 3.5.7: Bug fix: Heredoc/Nowdoc was not always handled correctly. PHPCS#2883
*
* @see \PHP_CodeSniffer\Files\File::findStartOfStatement() Original source.
*
Expand Down
2 changes: 1 addition & 1 deletion PHPCSUtils/BackCompat/BCTokens.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@
* @method static array methodPrefixes() Tokens that can prefix a method name.
* @method static array scopeModifiers() Tokens that represent scope modifiers.
* @method static array stringTokens() Tokens that represent strings.
* Note that `T_STRINGS` are NOT represented in this list as this list
* Note that `T_STRING`s are NOT represented in this list as this list
* is about _text_ strings.
*/
class BCTokens
Expand Down
47 changes: 26 additions & 21 deletions PHPCSUtils/Tokens/Collections.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,8 @@ class Collections
/**
* Tokens which are used to create arrays.
*
* @see \PHPCSUtils\Tokens\Collections::$arrayTokensBC Related property containing tokens used
* for arrays (PHPCS cross-version).
* @see \PHPCSUtils\Tokens\Collections::$shortArrayTokens Related property containing only tokens used
* for short arrays.
*
Expand All @@ -98,7 +100,7 @@ class Collections
* Should only be used selectively.
*
* @see \PHPCSUtils\Tokens\Collections::$shortArrayTokensBC Related property containing only tokens used
* for short arrays (cross-version).
* for short arrays (PHPCS cross-version).
*
* @since 1.0.0
*
Expand Down Expand Up @@ -180,6 +182,8 @@ class Collections
/**
* Tokens which are used to create lists.
*
* @see \PHPCSUtils\Tokens\Collections::$listTokensBC Related property containing tokens used
* for lists (PHPCS cross-version).
* @see \PHPCSUtils\Tokens\Collections::$shortListTokens Related property containing only tokens used
* for short lists.
*
Expand Down Expand Up @@ -252,8 +256,7 @@ class Collections
*
* @since 1.0.0-alpha3
*
* @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::objectOperators()}
* method instead.
* @deprecated 1.0.0-alpha4 Use the {@see Collections::objectOperators()} method instead.
*
* @var array <int> => <int>
*/
Expand Down Expand Up @@ -322,8 +325,7 @@ class Collections
*
* @since 1.0.0-alpha3
*
* @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::namespacedNameTokens()}
* method instead.
* @deprecated 1.0.0-alpha4 Use the {@see Collections::namespacedNameTokens()} method instead.
*
* @var array <int|string> => <int|string>
*/
Expand Down Expand Up @@ -351,11 +353,10 @@ class Collections
/**
* DEPRECATED: Token types which can be encountered in a parameter type declaration.
*
* @since 1.0.0
* @since 1.0.0-alpha1
*
* @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::parameterTypeTokens()}
* or {@see \PHPCSUtils\Tokens\Collections::parameterTypeTokensBC()}
* method instead.
* @deprecated 1.0.0-alpha4 Use the {@see Collections::parameterTypeTokens()} or
* {@see Collections::parameterTypeTokensBC()} method instead.
*
* @var array <int|string> => <int|string>
*/
Expand Down Expand Up @@ -385,11 +386,10 @@ class Collections
/**
* DEPRECATED: Token types which can be encountered in a property type declaration.
*
* @since 1.0.0
* @since 1.0.0-alpha1
*
* @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::propertyTypeTokens()}
* or {@see \PHPCSUtils\Tokens\Collections::propertyTypeTokensBC()}
* method instead.
* @deprecated 1.0.0-alpha4 Use the {@see Collections::propertyTypeTokens()} or
* {@see Collections::propertyTypeTokensBC()} method instead.
*
* @var array <int|string> => <int|string>
*/
Expand All @@ -404,11 +404,10 @@ class Collections
/**
* DEPRECATED: Token types which can be encountered in a return type declaration.
*
* @since 1.0.0
* @since 1.0.0-alpha1
*
* @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::returnTypeTokens()}
* or {@see \PHPCSUtils\Tokens\Collections::returnTypeTokensBC()}
* method instead.
* @deprecated 1.0.0-alpha4 Use the {@see Collections::returnTypeTokens()} or
* {@see Collections::returnTypeTokensBC()} method instead.
*
* @var array <int|string> => <int|string>
*/
Expand Down Expand Up @@ -508,6 +507,12 @@ class Collections
*
* Note: this is a method, not a property as the `T_FN` token for arrow functions may not exist.
*
* @see \PHPCSUtils\Utils\FunctionDeclarations::isArrowFunction() Determine whether an arbitrary token
* is in actual fact an arrow function
* keyword.
* @see \PHPCSUtils\Utils\FunctionDeclarations::getArrowFunctionOpenClose() Get an arrow function's parentheses
* and scope openers and closers.
*
* @since 1.0.0-alpha2
*
* @return array <int|string> => <int|string>
Expand Down Expand Up @@ -555,7 +560,7 @@ public static function functionCallTokens()
* Note: this is a method, not a property as the `T_FN` token for arrow functions may not exist.
*
* Sister-method to the {@see Collections::functionDeclarationTokensBC()} method.
* This method supports PHPCS 3.5.3 and up.
* This method supports PHPCS 3.5.3 and up.
* The {@see Collections::functionDeclarationTokensBC()} method supports PHPCS 2.6.0 and up.
*
* @see \PHPCSUtils\Tokens\Collections::functionDeclarationTokensBC() Related method (PHPCS 2.6.0+).
Expand Down Expand Up @@ -596,7 +601,7 @@ public static function functionDeclarationTokens()
* declaration or not.
*
* It is recommended to use the {@see Collections::functionDeclarationTokens()} method instead of
* this method if a standard supports does not need to support PHPCS < 3.5.3.
* this method if a standard does not need to support PHPCS < 3.5.3.
*
* @see \PHPCSUtils\Tokens\Collections::functionDeclarationTokens() Related method (PHPCS 3.5.3+).
* @see \PHPCSUtils\Utils\FunctionDeclarations::isArrowFunction() Arrow function verification.
Expand Down Expand Up @@ -695,7 +700,7 @@ public static function nameTokens()
*
* @see \PHPCSUtils\Tokens\Collections::objectOperatorsBC() Related method (PHPCS 2.6.0+).
*
* @since 1.0.0-alpha4
* @since 1.0.0-alpha4 This method replaces the {@see Collections::$objectOperators} property.
*
* @return array <int|string> => <int|string>
*/
Expand Down Expand Up @@ -890,7 +895,7 @@ public static function parameterTypeTokensBC()
{
$tokens = self::parameterTypeTokens();

// PHPCS < 4.0; Needed for support of PHPCS < 3.3.0. For PHPCS 3.3.0+ the constant is no longer used.
// PHPCS < 4.0; Needed for support of PHPCS < 3.3.0. As of PHPCS 3.3.0+ the constant is no longer used.
if (\defined('T_ARRAY_HINT') === true) {
$tokens[\T_ARRAY_HINT] = \T_ARRAY_HINT;
}
Expand Down
2 changes: 1 addition & 1 deletion PHPCSUtils/Utils/Arrays.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ public static function isShortArray(File $phpcsFile, $stackPtr)
return false;
}

// All known tokenizer bugs are in PHPCS versions before 3.5.6.
// All known tokenizer bugs are in PHPCS versions before 3.6.0.
$phpcsVersion = Helper::getVersion();

/*
Expand Down
4 changes: 2 additions & 2 deletions PHPCSUtils/Utils/Context.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ public static function inUnset(File $phpcsFile, $stackPtr)
* @param int $stackPtr The position of the token we are checking.
*
* @return string|false String `'beforeAs'`, `'as'` or `'afterAs'` when the token is within
* a foreach condition.
* a `foreach` condition.
* `FALSE` in all other cases, including for parse errors.
*/
public static function inForeachCondition(File $phpcsFile, $stackPtr)
Expand Down Expand Up @@ -146,7 +146,7 @@ public static function inForeachCondition(File $phpcsFile, $stackPtr)
* @param int $stackPtr The position of the token we are checking.
*
* @return string|false String `'expr1'`, `'expr2'` or `'expr3'` when the token is within
* a for condition.
* a `for` condition.
* `FALSE` in all other cases, including for parse errors.
*/
public static function inForCondition(File $phpcsFile, $stackPtr)
Expand Down
4 changes: 2 additions & 2 deletions PHPCSUtils/Utils/Lists.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,9 +107,9 @@ public static function isShortList(File $phpcsFile, $stackPtr)

$prevNonEmpty = $phpcsFile->findPrevious(Tokens::$emptyTokens, ($opener - 1), null, true);
if ((($prevNonEmpty === 0
&& isset(Collections::phpOpenTags()[$tokens[$prevNonEmpty]['code']]) === true) // Bug #1971.
&& isset(Collections::phpOpenTags()[$tokens[$prevNonEmpty]['code']]) === true) // Bug PHPCS#1971.
|| ($tokens[$prevNonEmpty]['code'] === \T_CLOSE_CURLY_BRACKET
&& isset($tokens[$prevNonEmpty]['scope_condition']))) // Bug #1284.
&& isset($tokens[$prevNonEmpty]['scope_condition']))) // Bug PHPCS#1284.
) {
$closer = $tokens[$opener]['bracket_closer'];
$nextNonEmpty = $phpcsFile->findNext(Tokens::$emptyTokens, ($closer + 1), null, true);
Expand Down
4 changes: 2 additions & 2 deletions PHPCSUtils/Utils/Parentheses.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
*
* @since 1.0.0
* @since 1.0.0-alpha4 Added support for `isset()`, `unset()`, `empty()`, `exit()`, `die()`
* and `eval()`` as parentheses owners to all applicable functions.
* and `eval()` as parentheses owners to all applicable functions.
*/
class Parentheses
{
Expand All @@ -34,7 +34,7 @@ class Parentheses
* Extra tokens which should be considered parentheses owners.
*
* - `T_LIST` and `T_ANON_CLASS` only became parentheses owners in PHPCS 3.5.0.
* - `T_ISSET`, `T_UNSET`, `T_EMPTY`, `T_EXIT` and `T_EVAL` are not PHPCS native parentheses,
* - `T_ISSET`, `T_UNSET`, `T_EMPTY`, `T_EXIT` and `T_EVAL` are not PHPCS native parentheses
* owners, but are considered such for the purposes of this class.
* Also {@see https://github.com/squizlabs/PHP_CodeSniffer/issues/3118}.
*
Expand Down
23 changes: 11 additions & 12 deletions PHPCSUtils/Utils/PassedParameters.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,16 +55,18 @@ class PassedParameters
* class instantiation function call when used like `new self()`.
* - If passed a `T_ARRAY` or `T_OPEN_SHORT_ARRAY` stack pointer, it will detect
* whether the array has values or is empty.
* For purposes of backward-compatibility with older PHPCS versions, `T_OPEN_SQUARE_BRACKET`
* tokens will also be accepted and will be checked whether they are in reality
* a short array opener.
* - If passed a `T_ISSET` or `T_UNSET` stack pointer, it will detect whether those
* language constructs have "parameters".
*
* @since 1.0.0
* @since 1.0.0-alpha4 Added support for PHP 8.0 identifier name tokenization.
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
* @param int $stackPtr The position of the `T_STRING`, PHP 8.0 identifier
* name token, `T_VARIABLE`, `T_ARRAY`, `T_OPEN_SHORT_ARRAY`,
* `T_ISSET`, or `T_UNSET` token.
* @param int $stackPtr The position of function call name,
* language construct or array open token.
* @param true|null $isShortArray Optional. Short-circuit the short array check for
* `T_OPEN_SHORT_ARRAY` tokens if it isn't necessary.
* Efficiency tweak for when this has already been established,
Expand Down Expand Up @@ -154,9 +156,8 @@ public static function hasParameters(File $phpcsFile, $stackPtr, $isShortArray =
* introducing the new `'name_start'`, `'name_end'` and `'name'` index keys.
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
* @param int $stackPtr The position of the `T_STRING`, PHP 8.0 identifier
* name token, `T_VARIABLE`, `T_ARRAY`, `T_OPEN_SHORT_ARRAY`,
* `T_ISSET`, or `T_UNSET` token.
* @param int $stackPtr The position of function call name,
* language construct or array open token.
* @param int $limit Optional. Limit the parameter retrieval to the first #
* parameters/array entries.
* @param true|null $isShortArray Optional. Short-circuit the short array check for
Expand Down Expand Up @@ -349,9 +350,8 @@ public static function getParameters(File $phpcsFile, $stackPtr, $limit = 0, $is
* @since 1.0.0
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
* @param int $stackPtr The position of the `T_STRING`, PHP 8.0 identifier
* name token, `T_VARIABLE`, `T_ARRAY`, `T_OPEN_SHORT_ARRAY`,
* `T_ISSET`, or `T_UNSET` token.
* @param int $stackPtr The position of function call name,
* language construct or array open token.
* @param int $paramOffset The 1-based index position of the parameter to retrieve.
* @param string|string[] $paramNames Optional. Either the name of the target parameter
* to retrieve as a string or an array of names for the
Expand Down Expand Up @@ -412,9 +412,8 @@ public static function getParameter(File $phpcsFile, $stackPtr, $paramOffset, $p
* @since 1.0.0
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
* @param int $stackPtr The position of the `T_STRING`, PHP 8.0 identifier
* name token, `T_VARIABLE`, `T_ARRAY`, `T_OPEN_SHORT_ARRAY`,
* `T_ISSET`, or `T_UNSET` token.
* @param int $stackPtr The position of function call name,
* language construct or array open token.
*
* @return int
*
Expand Down
7 changes: 6 additions & 1 deletion PHPCSUtils/Utils/UseStatements.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -299,7 +299,12 @@ public static function splitImportUseStatement(File $phpcsFile, $stackPtr)

case 'T_NAME_QUALIFIED':
case 'T_NAME_FULLY_QUALIFIED': // This would be a parse error, but handle it anyway.
// Only when either at the start of the statement or at the start of a new sub within a group.
/*
* PHPCS 4.x or PHP > 8.0 with PHPCS < 3.5.7.
*
* These tokens can only be encountered when either at the start of the statement
* or at the start of a new sub within a group.
*/
if ($start === true && $fixedType === false) {
$type = 'name';
}
Expand Down