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

Add sniff for 'void' in @return tags #1240

Open
wants to merge 15 commits into
base: develop
Choose a base branch
from
Open

Add sniff for 'void' in @return tags #1240

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
661df0b
Add sniff for 'void' in @return tags
dlh01 Nov 26, 2017
1d12603
Fix alignment errors
dlh01 Nov 26, 2017
91278c1
Fix unnecessary double quotes
dlh01 Nov 26, 2017
544d0d5
Remove extra `sprintf()`
dlh01 Nov 27, 2017
aad4720
Reference handbook rule in ruleset
dlh01 Nov 29, 2017
41ce582
Update @since tags
dlh01 Nov 29, 2017
1e40e6a
Replace extended error description with a recommendation
dlh01 Nov 29, 2017
ddc1b0d
Add tests with @return tag comments
dlh01 Nov 29, 2017
f8467b2
Remove `@return void` from internal docs
dlh01 Nov 29, 2017
1f41eec
Revert "Remove `@return void` from internal docs"
dlh01 Dec 10, 2017
8dc03a6
Generalize sniff files to accomodate other checks on return types
dlh01 Dec 10, 2017
7038b15
Move return checks into `process_return()` method
dlh01 Dec 10, 2017
3f7caab
Allow `void` with other return types
dlh01 Dec 10, 2017
2eeaacb
Exclude NoReturnVoid from internal ruleset
dlh01 Dec 10, 2017
5c0aeed
Merge branch 'develop' into no-return-void
dlh01 Dec 10, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions WordPress-Docs/ruleset.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,5 +117,6 @@
<exclude name="Generic.Commenting.Todo.TaskFound"/>
</rule>

<!-- WP disallows `@return void` outside of the default bundled themes -->
<rule ref="WordPress.Commenting.NoReturnVoid"/>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A comment could be added here referencing the handbook rule that this sniff relates to.

</ruleset>
2 changes: 0 additions & 2 deletions WordPress/AbstractArrayAssignmentRestrictionsSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,8 +124,6 @@ protected function setup_groups() {
* Processes this test, when one of its tokens is encountered.
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return void
*/
public function process_token( $stackPtr ) {

Expand Down
8 changes: 4 additions & 4 deletions WordPress/AbstractClassRestrictionsSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,8 +86,8 @@ public function register() {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My understanding is, that when a method could return a something or void, that @return int|voidis allowed.

What's not allowed is the case of simply @return void.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe @DrewAPicture could weigh in on this.

* normal file processing.
*/
public function process_token( $stackPtr ) {
// Reset the temporary storage before processing the token.
Expand Down Expand Up @@ -167,8 +167,8 @@ public function is_targetted_token( $stackPtr ) {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function check_for_matches( $stackPtr ) {
$skip_to = array();
Expand Down
12 changes: 6 additions & 6 deletions WordPress/AbstractFunctionParameterSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,8 @@ public function getGroups() {
* @param array $group_name The name of the group which was matched.
* @param string $matched_content The token content (function name) which was matched.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function process_matched_token( $stackPtr, $group_name, $matched_content ) {

Expand All @@ -87,8 +87,8 @@ public function process_matched_token( $stackPtr, $group_name, $matched_content
* @param string $matched_content The token content (function name) which was matched.
* @param array $parameters Array with information about the parameters.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
abstract public function process_parameters( $stackPtr, $group_name, $matched_content, $parameters );

Expand All @@ -102,8 +102,8 @@ abstract public function process_parameters( $stackPtr, $group_name, $matched_co
* @param array $group_name The name of the group which was matched.
* @param string $matched_content The token content (function name) which was matched.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function process_no_parameters( $stackPtr, $group_name, $matched_content ) {
return;
Expand Down
12 changes: 6 additions & 6 deletions WordPress/AbstractFunctionRestrictionsSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,8 +173,8 @@ protected function setup_groups( $key ) {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function process_token( $stackPtr ) {

Expand Down Expand Up @@ -248,8 +248,8 @@ public function is_targetted_token( $stackPtr ) {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function check_for_matches( $stackPtr ) {
$token_content = strtolower( $this->tokens[ $stackPtr ]['content'] );
Expand Down Expand Up @@ -287,8 +287,8 @@ public function check_for_matches( $stackPtr ) {
* @param string $group_name The name of the group which was matched.
* @param string $matched_content The token content (function name) which was matched.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function process_matched_token( $stackPtr, $group_name, $matched_content ) {

Expand Down
4 changes: 2 additions & 2 deletions WordPress/AbstractVariableRestrictionsSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,8 +129,8 @@ protected function setup_groups() {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function process_token( $stackPtr ) {

Expand Down
8 changes: 4 additions & 4 deletions WordPress/Sniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -877,8 +877,8 @@ abstract class Sniff implements PHPCS_Sniff {
* @param int $stackPtr The position of the current token
* in the stack passed in $tokens.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function process( File $phpcsFile, $stackPtr ) {
$this->init( $phpcsFile );
Expand All @@ -892,8 +892,8 @@ public function process( File $phpcsFile, $stackPtr ) {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
abstract public function process_token( $stackPtr );

Expand Down
2 changes: 0 additions & 2 deletions WordPress/Sniffs/Arrays/ArrayDeclarationSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,6 @@ public function register() {
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile A PHP_CodeSniffer file.
* @param int $stackPtr The position of the token.
*
* @return void
*/
public function process( File $phpcsFile, $stackPtr ) {}

Expand Down
6 changes: 0 additions & 6 deletions WordPress/Sniffs/Arrays/ArrayDeclarationSpacingSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,6 @@ public function register() {
* be in the `processSingleLineArray()` method.
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return void
*/
public function process_token( $stackPtr ) {
/*
Expand Down Expand Up @@ -176,8 +174,6 @@ public function process_token( $stackPtr ) {
* @param int $stackPtr The position of the current token in the stack.
* @param int $opener The position of the array opener.
* @param int $closer The position of the array closer.
*
* @return void
*/
protected function process_single_line_array( $stackPtr, $opener, $closer ) {
/*
Expand Down Expand Up @@ -333,8 +329,6 @@ protected function process_single_line_array( $stackPtr, $opener, $closer ) {
* @param int $stackPtr The position of the current token in the stack.
* @param int $opener The position of the array opener.
* @param int $closer The position of the array closer.
*
* @return void
*/
protected function process_multi_line_array( $stackPtr, $opener, $closer ) {
/*
Expand Down
2 changes: 0 additions & 2 deletions WordPress/Sniffs/Arrays/ArrayIndentationSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,6 @@ public function register() {
* Processes this test, when one of its tokens is encountered.
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return void
*/
public function process_token( $stackPtr ) {
if ( ! isset( $this->tab_width ) ) {
Expand Down
2 changes: 0 additions & 2 deletions WordPress/Sniffs/Arrays/ArrayKeySpacingRestrictionsSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,6 @@ public function register() {
* Processes this test, when one of its tokens is encountered.
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return void
*/
public function process_token( $stackPtr ) {

Expand Down
2 changes: 0 additions & 2 deletions WordPress/Sniffs/Arrays/CommaAfterArrayItemSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,6 @@ public function register() {
* Processes this test, when one of its tokens is encountered.
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return void
*/
public function process_token( $stackPtr ) {
/*
Expand Down
10 changes: 4 additions & 6 deletions WordPress/Sniffs/Arrays/MultipleStatementAlignmentSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,8 +160,8 @@ public function register() {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function process_token( $stackPtr ) {
/*
Expand Down Expand Up @@ -207,8 +207,8 @@ public function process_token( $stackPtr ) {
* @param int $opener The position of the array opener.
* @param int $closer The position of the array closer.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
protected function process_single_line_array( $stackPtr, $items, $opener, $closer ) {
/*
Expand Down Expand Up @@ -259,8 +259,6 @@ protected function process_single_line_array( $stackPtr, $items, $opener, $close
* @param array $items Info array containing information on each array item.
* @param int $opener The position of the array opener.
* @param int $closer The position of the array closer.
*
* @return void
*/
protected function process_multi_line_array( $stackPtr, $items, $opener, $closer ) {

Expand Down
4 changes: 0 additions & 4 deletions WordPress/Sniffs/CSRF/NonceVerificationSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,8 +125,6 @@ public function register() {
* Processes this test, when one of its tokens is encountered.
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return void
*/
public function process_token( $stackPtr ) {

Expand Down Expand Up @@ -168,8 +166,6 @@ public function process_token( $stackPtr ) {
* Merge custom functions provided via a custom ruleset with the defaults, if we haven't already.
*
* @since 0.11.0 Split out from the `process()` method.
*
* @return void
*/
protected function mergeFunctionLists() {
if ( $this->customNonceVerificationFunctions !== $this->addedCustomFunctions['nonce'] ) {
Expand Down
2 changes: 0 additions & 2 deletions WordPress/Sniffs/Classes/ClassInstantiationSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,8 +86,6 @@ public function register() {
* Processes this test, when one of its tokens is encountered.
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return void
*/
public function process_token( $stackPtr ) {
// Make sure we have the right token, JS vs PHP.
Expand Down
2 changes: 0 additions & 2 deletions WordPress/Sniffs/CodeAnalysis/AssignmentInConditionSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,8 +86,6 @@ public function register() {
* @since 0.14.0
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return void
*/
public function process_token( $stackPtr ) {

Expand Down
10 changes: 8 additions & 2 deletions WordPress/Sniffs/Commenting/NoReturnVoidSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
*
* @package WPCS\WordPressCodingStandards
*
* @since X.Y.Z
* @since 0.16.0
*/
class NoReturnVoidSniff extends Sniff {

Expand Down Expand Up @@ -86,8 +86,14 @@ public function process_token( $stackPtr ) {

foreach ( $returnTypes as $type ) {
if ( 'void' === $type ) {
$error = '`@return void` should not be used.';

$recommendation = ( count( $returnTypes ) > 1 )
? 'Remove it from the list of return types instead'
: 'Omit the `@return` tag instead';

$this->phpcsFile->addError(
sprintf( '`@return void` should not be used outside of the default bundled themes', $type ),
"$error $recommendation",
$returnTag,
'ReturnVoidFound'
);
Expand Down
2 changes: 0 additions & 2 deletions WordPress/Sniffs/DB/PreparedSQLPlaceholdersSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,8 +165,6 @@ public function register() {
* @since 0.14.0
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return void
*/
public function process_token( $stackPtr ) {

Expand Down
4 changes: 2 additions & 2 deletions WordPress/Sniffs/Files/FileNameSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,8 +130,8 @@ public function register() {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function process_token( $stackPtr ) {

Expand Down
14 changes: 6 additions & 8 deletions WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,8 +151,8 @@ public function getGroups() {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function process_token( $stackPtr ) {
/*
Expand Down Expand Up @@ -332,8 +332,8 @@ public function process_token( $stackPtr ) {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
protected function process_variable_variable( $stackPtr ) {
static $indicators = array(
Expand Down Expand Up @@ -429,8 +429,8 @@ protected function process_variable_variable( $stackPtr ) {
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
* @return int Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
protected function process_variable_assignment( $stackPtr ) {

Expand Down Expand Up @@ -567,8 +567,6 @@ protected function process_variable_assignment( $stackPtr ) {
* @param array $group_name The name of the group which was matched.
* @param string $matched_content The token content (function name) which was matched.
* @param array $parameters Array with information about the parameters.
*
* @return void
*/
public function process_parameters( $stackPtr, $group_name, $matched_content, $parameters ) {

Expand Down
4 changes: 0 additions & 4 deletions WordPress/Sniffs/NamingConventions/ValidFunctionNameSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,6 @@ class ValidFunctionNameSniff extends PHPCS_PEAR_ValidFunctionNameSniff {
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being processed.
* @param int $stackPtr The position where this token was
* found.
*
* @return void
*/
protected function processTokenOutsideScope( File $phpcsFile, $stackPtr ) {
$functionName = $phpcsFile->getDeclarationName( $stackPtr );
Expand Down Expand Up @@ -106,8 +104,6 @@ protected function processTokenOutsideScope( File $phpcsFile, $stackPtr ) {
* @param int $stackPtr The position where this token was
* found.
* @param int $currScope The position of the current scope.
*
* @return void
*/
protected function processTokenWithinScope( File $phpcsFile, $stackPtr, $currScope ) {
$methodName = $phpcsFile->getDeclarationName( $stackPtr );
Expand Down
2 changes: 0 additions & 2 deletions WordPress/Sniffs/NamingConventions/ValidHookNameSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,6 @@ public function getGroups() {
* @param array $group_name The name of the group which was matched.
* @param string $matched_content The token content (function name) which was matched.
* @param array $parameters Array with information about the parameters.
*
* @return void
*/
public function process_parameters( $stackPtr, $group_name, $matched_content, $parameters ) {
// Ignore deprecated hook names.
Expand Down