Merge pull request #770 from Automattic/feature/more-docs-fixes

WordPressVIPMinimum/Sniffs/Classes/DeclarationCompatibilitySniff.php

@@ -27,7 +27,7 @@ class DeclarationCompatibilitySniff extends AbstractScopeSniff {
 	/**
 	 * A list of classes and methods to check.
 	 *
-	 * @var string[]
+	 * @var array<string, array<string, array<string, mixed>>>
 	 */
 	public $checkClasses = [
 		'WP_Widget' => [
@@ -169,7 +169,7 @@ class DeclarationCompatibilitySniff extends AbstractScopeSniff {
 	/**
 	 * List of grouped classes with same methods (as they extend the same parent class)
 	 *
-	 * @var string[]
+	 * @var array<string, string[]>
 	 */
 	public $checkClassesGroups = [
 		'Walker' => [

WordPressVIPMinimum/Sniffs/Classes/RestrictedExtendClassesSniff.php

@@ -39,8 +39,9 @@ public function getGroups() {
 	 * Process a matched token.
 	 *
 	 * @param int    $stackPtr        The position of the current token in the stack.
-	 * @param array  $group_name      The name of the group which was matched.
-	 * @param string $matched_content The token content (class name) which was matched.
+	 * @param string $group_name      The name of the group which was matched.
+	 * @param string $matched_content The token content (class name) which was matched
+	 *                                in lowercase.
 	 *
 	 * @return void
 	 */

WordPressVIPMinimum/Sniffs/Functions/CheckReturnValueSniff.php

@@ -112,7 +112,7 @@ private function isFunctionCall( $stackPtr ) {
 	 *
 	 * @param int $stackPtr The position of the current token in the stack passed in $tokens.
 	 *
-	 * @return bool
+	 * @return int|false
 	 */
 	private function isVariableAssignment( $stackPtr ) {
 
@@ -140,6 +140,8 @@ private function isVariableAssignment( $stackPtr ) {
 	 * Find instances in which a function call is directly passed to another one w/o checking the return type
 	 *
 	 * @param int $stackPtr The position of the current token in the stack passed in $tokens.
+	 *
+	 * @return void
 	 */
 	public function findDirectFunctionCalls( $stackPtr ) {
 
@@ -290,8 +292,8 @@ public function findNonCheckedVariables( $stackPtr ) {
 	/**
 	 * Function used as as callback for the array_reduce call.
 	 *
-	 * @param string $carry The final string.
-	 * @param array  $item  Processed item.
+	 * @param string|null $carry The final string.
+	 * @param mixed       $item  Processed item.
 	 *
 	 * @return string
 	 */
@@ -305,6 +307,8 @@ public function reduce_array( $carry, $item ) {
 	 * @param int    $stackPtr     The position in the stack where the token was found.
 	 * @param string $variableName Variable name.
 	 * @param string $callee       Function name.
+	 *
+	 * @return void
 	 */
 	private function addNonCheckedVariableError( $stackPtr, $variableName, $callee ) {
 		$message = 'Type of `%s` must be checked before calling `%s()` using that variable.';

WordPressVIPMinimum/Sniffs/Functions/StripTagsSniff.php

@@ -41,9 +41,11 @@ class StripTagsSniff extends AbstractFunctionParameterSniff {
 	 * Process the parameters of a matched function.
 	 *
 	 * @param int    $stackPtr        The position of the current token in the stack.
-	 * @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 string $group_name      The name of the group which was matched.
+	 * @param string $matched_content The token content (function name) which was matched
+	 *                                in lowercase.
 	 * @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.
 	 */

WordPressVIPMinimum/Sniffs/Hooks/AlwaysReturnInFilterSniff.php

@@ -91,6 +91,8 @@ public function process_token( $stackPtr ) {
 	 * Process array.
 	 *
 	 * @param int $stackPtr The position in the stack where the token was found.
+	 *
+	 * @return void
 	 */
 	private function processArray( $stackPtr ) {
 
@@ -124,6 +126,8 @@ private function processArray( $stackPtr ) {
 	 * @param int $stackPtr The position in the stack where the token was found.
 	 * @param int $start    The start of the token.
 	 * @param int $end      The end of the token.
+	 *
+	 * @return void
 	 */
 	private function processString( $stackPtr, $start = 0, $end = null ) {
 
@@ -151,6 +155,8 @@ private function processString( $stackPtr, $start = 0, $end = null ) {
 	 * @param int $stackPtr The position in the stack where the token was found.
 	 * @param int $start    The start of the token.
 	 * @param int $end      The end of the token.
+	 *
+	 * @return void
 	 */
 	private function processFunction( $stackPtr, $start = 0, $end = null ) {
 
@@ -172,6 +178,8 @@ private function processFunction( $stackPtr, $start = 0, $end = null ) {
 	 * Process function's body
 	 *
 	 * @param int $stackPtr The position in the stack where the token was found.
+	 *
+	 * @return void
 	 */
 	private function processFunctionBody( $stackPtr ) {
 

WordPressVIPMinimum/Sniffs/Hooks/PreGetPostsSniff.php

@@ -92,6 +92,8 @@ public function process_token( $stackPtr ) {
 	 * Process array.
 	 *
 	 * @param int $stackPtr The position in the stack where the token was found.
+	 *
+	 * @return void
 	 */
 	private function processArray( $stackPtr ) {
 
@@ -114,6 +116,8 @@ private function processArray( $stackPtr ) {
 	 * Process string.
 	 *
 	 * @param int $stackPtr The position in the stack where the token was found.
+	 *
+	 * @return void
 	 */
 	private function processString( $stackPtr ) {
 
@@ -139,6 +143,8 @@ private function processString( $stackPtr ) {
 	 * Process function.
 	 *
 	 * @param int $stackPtr The position in the stack where the token was found.
+	 *
+	 * @return void
 	 */
 	private function processFunction( $stackPtr ) {
 
@@ -172,6 +178,8 @@ private function processFunction( $stackPtr ) {
 	 * Process closure.
 	 *
 	 * @param int $stackPtr The position in the stack where the token was found.
+	 *
+	 * @return void
 	 */
 	private function processClosure( $stackPtr ) {
 
@@ -197,6 +205,8 @@ private function processClosure( $stackPtr ) {
 	 *
 	 * @param int    $stackPtr     The position in the stack where the token was found.
 	 * @param string $variableName Variable name.
+	 *
+	 * @return void
 	 */
 	private function processFunctionBody( $stackPtr, $variableName ) {
 
@@ -236,6 +246,8 @@ private function processFunctionBody( $stackPtr, $variableName ) {
 	 * Consolidated violation.
 	 *
 	 * @param int $stackPtr The position in the stack where the token was found.
+	 *
+	 * @return void
 	 */
 	private function addPreGetPostsWarning( $stackPtr ) {
 		$message = 'Main WP_Query is being modified without `$query->is_main_query()` check. Needs manual inspection.';
@@ -362,8 +374,8 @@ private function isEarlyMainQueryCheck( $stackPtr ) {
 	/**
 	 * Is the current code a WP_Query call?
 	 *
-	 * @param int  $stackPtr The position in the stack where the token was found.
-	 * @param null $method   Method.
+	 * @param int         $stackPtr The position in the stack where the token was found.
+	 * @param string|null $method   Method.
 	 *
 	 * @return bool
 	 */

WordPressVIPMinimum/Sniffs/Hooks/RestrictedHooksSniff.php

@@ -76,9 +76,11 @@ class RestrictedHooksSniff extends AbstractFunctionParameterSniff {
 	 * Process the parameters of a matched function.
 	 *
 	 * @param int    $stackPtr        The position of the current token in the stack.
-	 * @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 string $group_name      The name of the group which was matched.
+	 * @param string $matched_content The token content (function name) which was matched
+	 *                                in lowercase.
 	 * @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.
 	 */
@@ -97,6 +99,7 @@ public function process_parameters( $stackPtr, $group_name, $matched_content, $p
 	 * Normalize hook name parameter.
 	 *
 	 * @param array $parameter Array with information about a parameter.
+	 *
 	 * @return string Normalized hook name.
 	 */
 	private function normalize_hook_name_from_parameter( $parameter ) {

WordPressVIPMinimum/Sniffs/JS/StringConcatSniff.php

@@ -67,6 +67,8 @@ public function process_token( $stackPtr ) {
 	 *
 	 * @param int   $stackPtr The position of the current token in the stack passed in $tokens.
 	 * @param array $data     Replacements for the error message.
+	 *
+	 * @return void
 	 */
 	private function addFoundError( $stackPtr, array $data ) {
 		$message = 'HTML string concatenation detected, this is a security risk, use DOM node construction or a templating language instead: %s.';

WordPressVIPMinimum/Sniffs/Performance/CacheValueOverrideSniff.php

@@ -113,7 +113,7 @@ private function isFunctionCall( $stackPtr ) {
 	 *
 	 * @param int $stackPtr The position of the current token in the stack.
 	 *
-	 * @return bool
+	 * @return int|false
 	 */
 	private function isVariableAssignment( $stackPtr ) {
 

WordPressVIPMinimum/Sniffs/Performance/LowExpiryCacheTimeSniff.php

@@ -60,9 +60,11 @@ class LowExpiryCacheTimeSniff extends AbstractFunctionParameterSniff {
 	 * Process the parameters of a matched function.
 	 *
 	 * @param int    $stackPtr        The position of the current token in the stack.
-	 * @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 string $group_name      The name of the group which was matched.
+	 * @param string $matched_content The token content (function name) which was matched
+	 *                                in lowercase.
 	 * @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.
 	 */

WordPressVIPMinimum/Sniffs/Security/PHPFilterFunctionsSniff.php

@@ -54,9 +54,11 @@ class PHPFilterFunctionsSniff extends AbstractFunctionParameterSniff {
 	 * Process the parameters of a matched function.
 	 *
 	 * @param int    $stackPtr        The position of the current token in the stack.
-	 * @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 string $group_name      The name of the group which was matched.
+	 * @param string $matched_content The token content (function name) which was matched
+	 *                                in lowercase.
 	 * @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.
 	 */

WordPressVIPMinimum/Sniffs/UserExperience/AdminBarRemovalSniff.php

@@ -190,8 +190,9 @@ public function process_token( $stackPtr ) {
 	 * Process the parameters of a matched function.
 	 *
 	 * @param int    $stackPtr        The position of the current token in the stack.
-	 * @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 string $group_name      The name of the group which was matched.
+	 * @param string $matched_content The token content (function name) which was matched
+	 *                                in lowercase.
 	 * @param array  $parameters      Array with information about the parameters.
 	 *
 	 * @return void
@@ -371,6 +372,8 @@ protected function process_css_style( $stackPtr ) {
 	 * Consolidated violation.
 	 *
 	 * @param int $stackPtr The position of the current token in the stack passed in $tokens.
+	 *
+	 * @return void
 	 */
 	private function addHidingDetectedError( $stackPtr ) {
 		$message = 'Hiding of the admin bar is not allowed.';

WordPressVIPMinimum/Tests/Classes/DeclarationCompatibilityUnitTest.php

@@ -21,7 +21,7 @@ class DeclarationCompatibilityUnitTest extends AbstractSniffUnitTest {
 	/**
 	 * Returns the lines where errors should occur.
 	 *
-	 * @return array <int line number> => <int number of errors>
+	 * @return array<int, int> Key is the line number, value is the number of expected errors.
 	 */
 	public function getErrorList() {
 		return [
@@ -55,7 +55,7 @@ public function getErrorList() {
 	/**
 	 * Returns the lines where warnings should occur.
 	 *
-	 * @return array <int line number> => <int number of warnings>
+	 * @return array<int, int> Key is the line number, value is the number of expected warnings.
 	 */
 	public function getWarningList() {
 		return [];

WordPressVIPMinimum/Tests/Classes/RestrictedExtendClassesUnitTest.php

@@ -21,7 +21,7 @@ class RestrictedExtendClassesUnitTest extends AbstractSniffUnitTest {
 	/**
 	 * Returns the lines where errors should occur.
 	 *
-	 * @return array <int line number> => <int number of errors>
+	 * @return array<int, int> Key is the line number, value is the number of expected errors.
 	 */
 	public function getErrorList() {
 		return [];
@@ -30,7 +30,7 @@ public function getErrorList() {
 	/**
 	 * Returns the lines where warnings should occur.
 	 *
-	 * @return array <int line number> => <int number of warnings>
+	 * @return array<int, int> Key is the line number, value is the number of expected warnings.
 	 */
 	public function getWarningList() {
 		return [

WordPressVIPMinimum/Tests/Constants/ConstantStringUnitTest.php

@@ -21,7 +21,7 @@ class ConstantStringUnitTest extends AbstractSniffUnitTest {
 	/**
 	 * Returns the lines where errors should occur.
 	 *
-	 * @return array <int line number> => <int number of errors>
+	 * @return array<int, int> Key is the line number, value is the number of expected errors.
 	 */
 	public function getErrorList() {
 		return [
@@ -33,7 +33,7 @@ public function getErrorList() {
 	/**
 	 * Returns the lines where warnings should occur.
 	 *
-	 * @return array <int line number> => <int number of warnings>
+	 * @return array<int, int> Key is the line number, value is the number of expected warnings.
 	 */
 	public function getWarningList() {
 		return [];

WordPressVIPMinimum/Tests/Constants/RestrictedConstantsUnitTest.php

@@ -21,7 +21,7 @@ class RestrictedConstantsUnitTest extends AbstractSniffUnitTest {
 	/**
 	 * Returns the lines where errors should occur.
 	 *
-	 * @return array <int line number> => <int number of errors>
+	 * @return array<int, int> Key is the line number, value is the number of expected errors.
 	 */
 	public function getErrorList() {
 		return [
@@ -34,7 +34,7 @@ public function getErrorList() {
 	/**
 	 * Returns the lines where warnings should occur.
 	 *
-	 * @return array <int line number> => <int number of warnings>
+	 * @return array<int, int> Key is the line number, value is the number of expected warnings.
 	 */
 	public function getWarningList() {
 		return [

WordPressVIPMinimum/Tests/Files/IncludingFileUnitTest.php

@@ -20,7 +20,7 @@ class IncludingFileUnitTest extends AbstractSniffUnitTest {
 	/**
 	 * Returns the lines where errors should occur.
 	 *
-	 * @return array <int line number> => <int number of errors>
+	 * @return array<int, int> Key is the line number, value is the number of expected errors.
 	 */
 	public function getErrorList() {
 		return [
@@ -36,7 +36,7 @@ public function getErrorList() {
 	/**
 	 * Returns the lines where warnings should occur.
 	 *
-	 * @return array <int line number> => <int number of warnings>
+	 * @return array<int, int> Key is the line number, value is the number of expected warnings.
 	 */
 	public function getWarningList() {
 		return [

WordPressVIPMinimum/Tests/Files/IncludingNonPHPFileUnitTest.php

@@ -21,7 +21,7 @@ class IncludingNonPHPFileUnitTest extends AbstractSniffUnitTest {
 	/**
 	 * Returns the lines where errors should occur.
 	 *
-	 * @return array <int line number> => <int number of errors>
+	 * @return array<int, int> Key is the line number, value is the number of expected errors.
 	 */
 	public function getErrorList() {
 		return [
@@ -54,7 +54,7 @@ public function getErrorList() {
 	/**
 	 * Returns the lines where warnings should occur.
 	 *
-	 * @return array <int line number> => <int number of warnings>
+	 * @return array<int, int> Key is the line number, value is the number of expected warnings.
 	 */
 	public function getWarningList() {
 		return [];

WordPressVIPMinimum/Tests/Functions/CheckReturnValueUnitTest.php

@@ -21,7 +21,7 @@ class CheckReturnValueUnitTest extends AbstractSniffUnitTest {
 	/**
 	 * Returns the lines where errors should occur.
 	 *
-	 * @return array <int line number> => <int number of errors>
+	 * @return array<int, int> Key is the line number, value is the number of expected errors.
 	 */
 	public function getErrorList() {
 		return [
@@ -36,7 +36,7 @@ public function getErrorList() {
 	/**
 	 * Returns the lines where warnings should occur.
 	 *
-	 * @return array <int line number> => <int number of warnings>
+	 * @return array<int, int> Key is the line number, value is the number of expected warnings.
 	 */
 	public function getWarningList() {
 		return [];