Skip to content

Commit

Permalink
Streamline WPCS in file documentation. (#651)
Browse files Browse the repository at this point in the history 
* Update the file and class @Package tag and remove the @category tag.

Follow the standard as described in https://www.phpdoc.org/docs/latest/references/phpdoc/tags/package.html

The @category tag is considered deprecated. A hierarchical @Package tag should be used instead.

Ref: https://www.phpdoc.org/docs/latest/references/phpdoc/tags/category.html

* Use correct version number for the newly deprecated classes.

* Fix some - unintentional - parse errors in the test files.

* Attempt to lead by example comment-wise in the unit tests.

Capitalization, punctuation and some spelling.

* Proper capitalization and punctuation for class end comments.

* Remove `//end` comments for methods and conditionals < 35 lines.

* Simplify the test file method doc blocks.

* Various documentation fixes, largely based on PHPCS Docs output.

* Make sure any function which will be passed the $phpcsFile has the right type hint.

But only if it doesn't conflict with upstream function signatures.

* Verify and update the docblocks for all files and classes.

Based on Git file history:

* Add @SInCE tags to all classes.
* Add @SInCE tags to properties and methods if they weren't included from the start.
* Verify/Fix a number of @author tags.
* Remove old/copied over/incorrect PHPCS tags.
* Where necessary improved/corrected the class description.

Also:
* Consistent tag order in class doc blocks.
* Fix tag alignment.
* Remove redundant explanation in unit test class doc blocks.
* Sync the description line of the unit test class doc blocks.

* Add handbook links to a number of sniffs.

* Add reference to upstream sniff a sniff is based upon.

Includes information on when the sniff was last synced with the upstream sniff if applicable and available.

* Add @license tag and @link tag to the WPCS GH repo, to all file level doc blocks.

License tag as per https://www.phpdoc.org/docs/latest/references/phpdoc/tags/license.html

* Add the docs ruleset to the coding standard for WPCS itself.

* Add @SInCE class changelogs for PR #647.

* Fix minor grammar error.

* Updated `@since` tags for `2014-12-11` release to `0.3.0`.

* Re-instate previously removed @SInCE tags.

* Updated based on feedback.

* Adjusted the @Package tags as per discussion in the PR thread
* Removed the @link tag to the handbook at the file level doc block
* Removed the @author tags
  • Loading branch information
@jrfnl @westonruter
jrfnl authored and westonruter committed Aug 18, 2016
1 parent 1939480 commit f60bfe5
Show file tree
Hide file tree
Showing 133 changed files with 1,950 additions and 2,237 deletions.
20 changes: 12 additions & 8 deletions WordPress/AbstractArrayAssignmentRestrictionsSniff.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,21 @@
/**
* WordPress Coding Standard.
*
* @category PHP
* @package PHP_CodeSniffer
* @link https://make.wordpress.org/core/handbook/best-practices/coding-standards/
* @package WPCS\WordPressCodingStandards
* @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
* @license https://opensource.org/licenses/MIT MIT
*/

/**
* Restricts array assignment of certain keys.
*
* @category PHP
* @package PHP_CodeSniffer
* @author Shady Sharaf <[email protected]>
* @package WPCS\WordPressCodingStandards
*
* @since 0.3.0
* @since 0.10.0 Class became a proper abstract class. This was already the behaviour.
* Moved the file and renamed the class from
* `WordPress_Sniffs_Arrays_ArrayAssignmentRestrictionsSniff` to
* `WordPress_AbstractArrayAssignmentRestrictionsSniff`.
*/
abstract class WordPress_AbstractArrayAssignmentRestrictionsSniff extends WordPress_Sniff {

Expand Down Expand Up @@ -47,7 +51,7 @@ public function register() {
T_DOUBLE_QUOTED_STRING,
);

} // end register()
}

/**
* Groups of variables to restrict.
Expand Down Expand Up @@ -195,4 +199,4 @@ public function process( PHP_CodeSniffer_File $phpcsFile, $stackPtr ) {
*/
abstract public function callback( $key, $val, $line, $group );

} // end class
} // End class.
45 changes: 23 additions & 22 deletions WordPress/AbstractClassRestrictionsSniff.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@
/**
* WordPress Coding Standard.
*
* @category PHP
* @package PHP_CodeSniffer
* @link https://make.wordpress.org/core/handbook/best-practices/coding-standards/
* @package WPCS\WordPressCodingStandards
* @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
* @license https://opensource.org/licenses/MIT MIT
*/

/**
* Restricts usage of some classes.
*
* @category PHP
* @package PHP_CodeSniffer
* @author Juliette Reinders Folmer <[email protected]>
* @package WPCS\WordPressCodingStandards
*
* @since 0.10.0
*/
abstract class WordPress_AbstractClassRestrictionsSniff extends WordPress_AbstractFunctionRestrictionsSniff {

Expand Down Expand Up @@ -51,8 +51,9 @@ abstract class WordPress_AbstractClassRestrictionsSniff extends WordPress_Abstra
* Documented here for clarity. Not (re)defined as it is already defined in the parent class.
*
* @return array
*
abstract public function getGroups();
*/
// abstract public function getGroups();

/**
* Returns an array of tokens this test wants to listen for.
Expand All @@ -72,7 +73,7 @@ public function register() {
T_IMPLEMENTS,
);

} // end register()
}

/**
* Processes this test, when one of its tokens is encountered.
Expand Down Expand Up @@ -178,13 +179,13 @@ protected function prepare_name_for_regex( $classname ) {
/**
* See if the classname was found in a namespaced file and if so, add the namespace to the classname.
*
* @param string $classname The full classname as found.
* @param object $phpcsFile Instance of phpcsFile.
* @param array $tokens The token stack for this file.
* @param int $search_from The token position to search up from.
* @param string $classname The full classname as found.
* @param PHP_CodeSniffer_File $phpcsFile The file being scanned.
* @param array $tokens The token stack for this file.
* @param int $search_from The token position to search up from.
* @return string Classname, potentially prefixed with the namespace.
*/
protected function get_namespaced_classname( $classname, $phpcsFile, $tokens, $search_from ) {
protected function get_namespaced_classname( $classname, PHP_CodeSniffer_File $phpcsFile, $tokens, $search_from ) {
// Don't do anything if this is already a fully qualified classname.
if ( empty( $classname ) || '\\' === $classname[0] ) {
return $classname;
Expand Down Expand Up @@ -216,12 +217,12 @@ protected function get_namespaced_classname( $classname, $phpcsFile, $tokens, $s
/**
* Determine the namespace name based on whether this is a scoped namespace or a file namespace.
*
* @param object $phpcsFile Instance of phpcsFile.
* @param array $tokens The token stack for this file.
* @param int $search_from The token position to search up from.
* @param PHP_CodeSniffer_File $phpcsFile The file being scanned.
* @param array $tokens The token stack for this file.
* @param int $search_from The token position to search up from.
* @return string Namespace name or empty string if it couldn't be determined or no namespace applied.
*/
protected function determine_namespace( $phpcsFile, $tokens, $search_from ) {
protected function determine_namespace( PHP_CodeSniffer_File $phpcsFile, $tokens, $search_from ) {
$namespace = '';

if ( ! empty( $tokens[ $search_from ]['conditions'] ) ) {
Expand All @@ -247,17 +248,17 @@ protected function determine_namespace( $phpcsFile, $tokens, $search_from ) {
/**
* Get the namespace name based on the position of the namespace scope opener.
*
* @param object $phpcsFile Instance of phpcsFile.
* @param array $tokens The token stack for this file.
* @param int $t_namespace_token The token position to search from.
* @param PHP_CodeSniffer_File $phpcsFile The file being scanned.
* @param array $tokens The token stack for this file.
* @param int $t_namespace_token The token position to search from.
* @return string Namespace name.
*/
protected function get_namespace_name( $phpcsFile, $tokens, $t_namespace_token ) {
protected function get_namespace_name( PHP_CodeSniffer_File $phpcsFile, $tokens, $t_namespace_token ) {
$nameEnd = ( $phpcsFile->findNext( array( T_OPEN_CURLY_BRACKET, T_WHITESPACE, T_SEMICOLON ), ( $t_namespace_token + 2 ) ) - 1 );
$length = ( $nameEnd - ( $t_namespace_token + 1 ) );
$namespace = $phpcsFile->getTokensAsString( ( $t_namespace_token + 2 ), $length );

return $namespace;
}

} // end class
} // End class.
18 changes: 11 additions & 7 deletions WordPress/AbstractFunctionRestrictionsSniff.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,21 @@
/**
* WordPress Coding Standard.
*
* @category PHP
* @package PHP_CodeSniffer
* @link https://make.wordpress.org/core/handbook/best-practices/coding-standards/
* @package WPCS\WordPressCodingStandards
* @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
* @license https://opensource.org/licenses/MIT MIT
*/

/**
* Restricts usage of some functions.
*
* @category PHP
* @package PHP_CodeSniffer
* @author Shady Sharaf <[email protected]>
* @package WPCS\WordPressCodingStandards
*
* @since 0.3.0
* @since 0.10.0 Class became a proper abstract class. This was already the behaviour.
* Moved the file and renamed the class from
* `WordPress_Sniffs_Functions_FunctionRestrictionsSniff` to
* `WordPress_AbstractFunctionRestrictionsSniff`.
*/
abstract class WordPress_AbstractFunctionRestrictionsSniff implements PHP_CodeSniffer_Sniff {

Expand Down Expand Up @@ -209,4 +213,4 @@ protected function prepare_name_for_regex( $function ) {
return $function;
}

} // end class
} // End class.
32 changes: 21 additions & 11 deletions WordPress/AbstractVariableRestrictionsSniff.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,21 @@
/**
* WordPress Coding Standard.
*
* @category PHP
* @package PHP_CodeSniffer
* @link https://make.wordpress.org/core/handbook/best-practices/coding-standards/
* @package WPCS\WordPressCodingStandards
* @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
* @license https://opensource.org/licenses/MIT MIT
*/

/**
* Restricts usage of some variables.
*
* @category PHP
* @package PHP_CodeSniffer
* @author Shady Sharaf <[email protected]>
* @package WPCS\WordPressCodingStandards
*
* @since 0.3.0
* @since 0.10.0 Class became a proper abstract class. This was already the behaviour.
* Moved the file and renamed the class from
* `WordPress_Sniffs_Variables_VariableRestrictionsSniff` to
* `WordPress_AbstractVariableRestrictionsSniff`.
*/
abstract class WordPress_AbstractVariableRestrictionsSniff implements PHP_CodeSniffer_Sniff {

Expand Down Expand Up @@ -48,7 +52,7 @@ public function register() {
T_DOUBLE_QUOTED_STRING,
);

} // end register()
}

/**
* Groups of variables to restrict.
Expand Down Expand Up @@ -76,7 +80,7 @@ abstract public function getGroups();
* @param int $stackPtr The position of the current token
* in the stack passed in $tokens.
*
* @return void
* @return int|void If no groups are found, a stack pointer to indicate to skip the current one is passed.
*/
public function process( PHP_CodeSniffer_File $phpcsFile, $stackPtr ) {
$tokens = $phpcsFile->getTokens();
Expand Down Expand Up @@ -111,7 +115,7 @@ public function process( PHP_CodeSniffer_File $phpcsFile, $stackPtr ) {
$var = $token['content'];

} elseif ( in_array( $token['code'], array( T_OBJECT_OPERATOR, T_DOUBLE_COLON, T_DOUBLE_QUOTED_STRING ), true ) && ! empty( $group['object_vars'] ) ) {
// Object var, ex: $foo->bar / $foo::bar / Foo::bar / Foo::$bar
// Object var, ex: $foo->bar / $foo::bar / Foo::bar / Foo::$bar .
$patterns = array_merge( $patterns, $group['object_vars'] );

$owner = $phpcsFile->findPrevious( array( T_VARIABLE, T_STRING ), $stackPtr );
Expand Down Expand Up @@ -165,6 +169,12 @@ public function process( PHP_CodeSniffer_File $phpcsFile, $stackPtr ) {

} // end process()

/**
* Transform a wildcard pattern to a usable regex pattern.
*
* @param string $pattern Pattern.
* @return string
*/
private function test_patterns( $pattern ) {
$pattern = preg_quote( $pattern, '#' );
$pattern = preg_replace(
Expand All @@ -173,6 +183,6 @@ private function test_patterns( $pattern ) {
$pattern
);
return $pattern;
} // end test_patterns()
}

} // end class
} // End class.
37 changes: 19 additions & 18 deletions WordPress/Sniff.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,18 @@
/**
* Represents a PHP_CodeSniffer sniff for sniffing WordPress coding standards.
*
* @category PHP
* @package PHP_CodeSniffer
* @package WPCS\WordPressCodingStandards
* @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
* @license https://opensource.org/licenses/MIT MIT
*/

/**
* Represents a PHP_CodeSniffer sniff for sniffing WordPress coding standards.
*
* Provides a bootstrap for the sniffs, to reduce code duplication.
*
* @category PHP
* @package PHP_CodeSniffer
* @version 0.4.0
* @link http://pear.php.net/package/PHP_CodeSniffer
* @package WPCS\WordPressCodingStandards
* @since 0.4.0
*/
abstract class WordPress_Sniff implements PHP_CodeSniffer_Sniff {

Expand Down Expand Up @@ -461,7 +460,7 @@ abstract class WordPress_Sniff implements PHP_CodeSniffer_Sniff {
/**
* A list of superglobals that incorporate user input.
*
* @since 0.4.0
* @since 0.5.0
*
* @var string[]
*/
Expand Down Expand Up @@ -578,7 +577,7 @@ protected function has_whitelist_comment( $comment, $stackPtr ) {
*
* $array['key'][ $foo ][ something() ] = $bar;
*
* @since 0.4.0
* @since 0.5.0
*
* @param int $stackPtr The index of the token in the stack. This must points to
* either a T_VARIABLE or T_CLOSE_SQUARE_BRACKET token.
Expand Down Expand Up @@ -613,7 +612,7 @@ protected function is_assignment( $stackPtr ) {
return true;
}

// Check if this is an array assignment, e.g., $var['key'] = 'val';
// Check if this is an array assignment, e.g., `$var['key'] = 'val';` .
if ( T_OPEN_SQUARE_BRACKET === $tokens[ $next_non_empty ]['code'] ) {
return $this->is_assignment( $tokens[ $next_non_empty ]['bracket_closer'] );
}
Expand All @@ -633,14 +632,14 @@ protected function is_assignment( $stackPtr ) {
protected function has_nonce_check( $stackPtr ) {

/**
* @var array {
* A cache of the scope that we last checked for nonce verification in.
* A cache of the scope that we last checked for nonce verification in.
*
* @var string $file The name of the file.
* @var int $start The index of the token where the scope started.
* @var int $end The index of the token where the scope ended.
* @var bool|int $nonce_check The index of the token where an nonce
* check was found, or false if none was found.
* @var array {
* @var string $file The name of the file.
* @var int $start The index of the token where the scope started.
* @var int $end The index of the token where the scope ended.
* @var bool|int $nonce_check The index of the token where an nonce check
* was found, or false if none was found.
* }
*/
static $last;
Expand Down Expand Up @@ -973,7 +972,6 @@ protected function get_array_access_key( $stackPtr ) {
protected function is_validated( $stackPtr, $array_key = null, $in_condition_only = false ) {

if ( $in_condition_only ) {

/*
This is a stricter check, requiring the variable to be used only
within the validation condition.
Expand Down Expand Up @@ -1004,7 +1002,6 @@ protected function is_validated( $stackPtr, $array_key = null, $in_condition_onl
$scope_end = $condition['parenthesis_closer'];

} else {

/*
We are are more loose, requiring only that the variable be validated
in the same function/file scope as it is used.
Expand Down Expand Up @@ -1130,6 +1127,8 @@ protected function is_comparison( $stackPtr ) {
* This function will check the token and return 'closure', 'trait', or 'class',
* based on which of these uses the use is being used for.
*
* @since 0.7.0
*
* @param int $stackPtr The position of the token to check.
*
* @return string The type of use.
Expand Down Expand Up @@ -1157,6 +1156,8 @@ protected function get_use_type( $stackPtr ) {
*
* Check if '$' is followed by a valid variable name, and that it is not preceded by an escape sequence.
*
* @since 0.9.0
*
* @param string $string A T_DOUBLE_QUOTED_STRING token.
*
* @return array Variable names (without '$' sigil).
Expand Down
Loading

0 comments on commit f60bfe5

Please sign in to comment.