Add sniff for 'void' in @return tags

WordPress-Docs/ruleset.xml

@@ -116,4 +116,7 @@
 		<!-- WP allows @todo's in comments -->
 		<exclude name="Generic.Commenting.Todo.TaskFound"/>
 	</rule>
+
+	<!-- WP disallows `@return void` outside of the default bundled themes -->
+	<rule ref="WordPress.Commenting.NoReturnVoid"/>
 </ruleset>

WordPress/AbstractArrayAssignmentRestrictionsSniff.php

@@ -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 ) {
 

WordPress/AbstractClassRestrictionsSniff.php

@@ -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
+	 *             normal file processing.
 	 */
 	public function process_token( $stackPtr ) {
 		// Reset the temporary storage before processing the token.
@@ -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();

WordPress/AbstractFunctionParameterSniff.php

@@ -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 ) {
 
@@ -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 );
 
@@ -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;

WordPress/AbstractFunctionRestrictionsSniff.php

@@ -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 ) {
 
@@ -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'] );
@@ -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 ) {
 

WordPress/AbstractVariableRestrictionsSniff.php

@@ -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 ) {
 

WordPress/Sniff.php

@@ -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 );
@@ -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 );
 

WordPress/Sniffs/Arrays/ArrayDeclarationSniff.php

@@ -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 ) {}
 

WordPress/Sniffs/Arrays/ArrayDeclarationSpacingSniff.php

@@ -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 ) {
 		/*
@@ -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 ) {
 		/*
@@ -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 ) {
 		/*

WordPress/Sniffs/Arrays/ArrayIndentationSniff.php

@@ -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 ) ) {

WordPress/Sniffs/Arrays/ArrayKeySpacingRestrictionsSniff.php

@@ -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 ) {
 

WordPress/Sniffs/Arrays/CommaAfterArrayItemSniff.php

@@ -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 ) {
 		/*

WordPress/Sniffs/Arrays/MultipleStatementAlignmentSniff.php

@@ -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 ) {
 		/*
@@ -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 ) {
 		/*
@@ -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 ) {
 

WordPress/Sniffs/CSRF/NonceVerificationSniff.php

@@ -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 ) {
 
@@ -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'] ) {

WordPress/Sniffs/Classes/ClassInstantiationSniff.php

@@ -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.

WordPress/Sniffs/CodeAnalysis/AssignmentInConditionSniff.php

@@ -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 ) {
 

WordPress/Sniffs/Commenting/NoReturnVoidSniff.php

@@ -0,0 +1,106 @@
+<?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @package WPCS\WordPressCodingStandards
+ * @link    https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
+ * @license https://opensource.org/licenses/MIT MIT
+ */
+
+namespace WordPress\Sniffs\Commenting;
+
+use WordPress\Sniff;
+use PHP_CodeSniffer_Tokens as Tokens;
+
+/**
+ * Disallows the 'void' return type.
+ *
+ * @link    https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#phpdoc-tags
+ *
+ * @package WPCS\WordPressCodingStandards
+ *
+ * @since   0.16.0
+ */
+class NoReturnVoidSniff extends Sniff {
+
+	/**
+	 * Registers the tokens that this sniff wants to listen for.
+	 *
+	 * @return array
+	 */
+	public function register() {
+		return array( T_FUNCTION );
+	}
+
+	/**
+	 * Processes this test when one of its tokens is encountered.
+	 *
+	 * @param int $stackPtr The position of the current token in the stack.
+	 * @return int Integer stack pointer to skip the rest of the file.
+	 */
+	public function process_token( $stackPtr ) {
+		$commentEnd = $this->phpcsFile->findPrevious(
+			array_merge( Tokens::$methodPrefixes, array( T_WHITESPACE ) ),
+			( $stackPtr - 1 ),
+			null,
+			true
+		);
+
+		if ( T_DOC_COMMENT_CLOSE_TAG !== $this->tokens[ $commentEnd ]['code'] ) {
+			// Invalid function comment. Handled elsewhere.
+			return;
+		}
+
+		$commentStart = $this->tokens[ $commentEnd ]['comment_opener'];
+
+		$returnTag = null;
+
+		foreach ( $this->tokens[ $commentStart ]['comment_tags'] as $tag ) {
+			if ( '@return' === $this->tokens[ $tag ]['content'] ) {
+				$returnTag = $tag;
+				// Multiple return tags are invalid, but flagged elsewhere.
+				break;
+			}
+		}
+
+		if ( ! $returnTag ) {
+			return;
+		}
+
+		$returnCommentPtr = ( $returnTag + 2 );
+		$returnComment    = $this->tokens[ $returnCommentPtr ];
+
+		if ( empty( $returnComment['content'] ) || T_DOC_COMMENT_STRING !== $returnComment['code'] ) {
+			// Invalid return comment. Handled elsewhere.
+			return;
+		}
+
+		// Extracted from PHP_CodeSniffer\Standards\Squiz\Sniffs\Commenting\FunctionCommentSniff::processReturn().
+		preg_match( '`^((?:\|?(?:array\([^\)]*\)|[\\\\a-z0-9\[\]]+))*)( .*)?`i', $returnComment['content'], $commentParts );
+
+		if ( empty( $commentParts[1] ) ) {
+			return;
+		}
+
+		$returnTypes = array_unique( explode( '|', $commentParts[1] ) );
+
+		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(
+					"$error $recommendation",
+					$returnTag,
+					'ReturnVoidFound'
+				);
+
+				break;
+			}
+		}
+	}
+
+}

WordPress/Sniffs/DB/PreparedSQLPlaceholdersSniff.php

@@ -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 ) {
 

WordPress/Sniffs/Files/FileNameSniff.php

@@ -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 ) {