Merge pull request #826 from Automattic/feature/docs-improve-specificity

WordPressVIPMinimum/Sniffs/AbstractVariableRestrictionsSniff.php

@@ -58,7 +58,7 @@ abstract class AbstractVariableRestrictionsSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		// Retrieve the groups only once and don't set up a listener if there are no groups.
@@ -91,7 +91,7 @@ public function register() {
 	 *  )
 	 * )
 	 *
-	 * @return array
+	 * @return array<string, array<string, string|array<string>>>
 	 */
 	abstract public function getGroups();
 

WordPressVIPMinimum/Sniffs/Classes/DeclarationCompatibilitySniff.php

@@ -27,7 +27,7 @@ class DeclarationCompatibilitySniff extends AbstractScopeSniff {
 	/**
 	 * A list of classes and methods to check.
 	 *
-	 * @var array<string, array<string, array<string, mixed>>>
+	 * @var array<string, array<string, array<int|string, string|array<string, bool|string>>>>
 	 */
 	public $checkClasses = [
 		'WP_Widget' => [
@@ -315,7 +315,7 @@ private function addError( $parentClassName, $methodName, $currentMethodSignatur
 	 *
 	 * @param array $methodSignature Signature of a method.
 	 *
-	 * @return array
+	 * @return array<string>
 	 */
 	private function generateParamList( $methodSignature ) {
 		$paramList = [];

WordPressVIPMinimum/Sniffs/Classes/RestrictedExtendClassesSniff.php

@@ -19,7 +19,7 @@ class RestrictedExtendClassesSniff extends AbstractClassRestrictionsSniff {
 	/**
 	 * Groups of classes to restrict.
 	 *
-	 * @return array
+	 * @return array<string, array<string, string|array<string>>>
 	 */
 	public function getGroups() {
 		return [

WordPressVIPMinimum/Sniffs/Constants/ConstantStringSniff.php

@@ -20,7 +20,7 @@ class ConstantStringSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [

WordPressVIPMinimum/Sniffs/Constants/RestrictedConstantsSniff.php

@@ -19,7 +19,7 @@ class RestrictedConstantsSniff extends Sniff {
 	/**
 	 * List of restricted constant names.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	public $restrictedConstantNames = [
 		'A8C_PROXIED_REQUEST',
@@ -28,7 +28,7 @@ class RestrictedConstantsSniff extends Sniff {
 	/**
 	 * List of restricted constant declarations.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	public $restrictedConstantDeclaration = [
 		'JETPACK_DEV_DEBUG',
@@ -38,7 +38,7 @@ class RestrictedConstantsSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [

WordPressVIPMinimum/Sniffs/Files/IncludingFileSniff.php

@@ -20,7 +20,7 @@ class IncludingFileSniff extends AbstractFunctionRestrictionsSniff {
 	/**
 	 * List of function used for getting paths.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	public $getPathFunctions = [
 		'dirname',
@@ -55,7 +55,7 @@ class IncludingFileSniff extends AbstractFunctionRestrictionsSniff {
 	/**
 	 * List of restricted constants.
 	 *
-	 * @var array
+	 * @var array<string, string>
 	 */
 	public $restrictedConstants = [
 		'TEMPLATEPATH'   => 'get_template_directory',
@@ -65,7 +65,7 @@ class IncludingFileSniff extends AbstractFunctionRestrictionsSniff {
 	/**
 	 * List of allowed constants.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	public $allowedConstants = [
 		'ABSPATH',
@@ -77,7 +77,7 @@ class IncludingFileSniff extends AbstractFunctionRestrictionsSniff {
 	 * List of keywords allowed for use in custom constants.
 	 * Note: Customizing this property will overwrite current default values.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	public $allowedKeywords = [
 		'PATH',
@@ -87,7 +87,7 @@ class IncludingFileSniff extends AbstractFunctionRestrictionsSniff {
 	/**
 	 * Functions used for modify slashes.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	public $slashingFunctions = [
 		'trailingslashit',
@@ -107,7 +107,7 @@ public function getGroups() {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return Tokens::$includeTokens;

WordPressVIPMinimum/Sniffs/Files/IncludingNonPHPFileSniff.php

@@ -23,7 +23,7 @@ class IncludingNonPHPFileSniff extends Sniff {
 	 *
 	 * Files with these extensions are allowed to be `include`d.
 	 *
-	 * @var array Key is the extension, value is irrelevant.
+	 * @var array<string, bool> Key is the extension, value is irrelevant.
 	 */
 	private $php_extensions = [
 		'php'  => true,
@@ -34,7 +34,7 @@ class IncludingNonPHPFileSniff extends Sniff {
 	/**
 	 * File extensions used for SVG and CSS files.
 	 *
-	 * @var array Key is the extension, value is irrelevant.
+	 * @var array<string, bool> Key is the extension, value is irrelevant.
 	 */
 	private $svg_css_extensions = [
 		'css' => true,
@@ -44,7 +44,7 @@ class IncludingNonPHPFileSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return Tokens::$includeTokens;

WordPressVIPMinimum/Sniffs/Functions/CheckReturnValueSniff.php

@@ -24,7 +24,7 @@ class CheckReturnValueSniff extends Sniff {
 	/**
 	 * Pairs we are about to check.
 	 *
-	 * @var array
+	 * @var array<string, array<string>>
 	 */
 	public $catch = [
 		'esc_url'          => [
@@ -48,7 +48,7 @@ class CheckReturnValueSniff extends Sniff {
 	/**
 	 * Tokens we are about to examine, which are not functions.
 	 *
-	 * @var array
+	 * @var array<string, int|string>
 	 */
 	public $notFunctions = [
 		'foreach' => T_FOREACH,
@@ -57,7 +57,7 @@ class CheckReturnValueSniff extends Sniff {
 	/**
 	 * Returns the token types that this sniff is interested in.
 	 *
-	 * @return array(int)
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [ T_STRING ];
@@ -293,7 +293,7 @@ public function findNonCheckedVariables( $stackPtr ) {
 	 * Function used as as callback for the array_reduce call.
 	 *
 	 * @param string|null $carry The final string.
-	 * @param mixed       $item  Processed item.
+	 * @param array       $item  Processed item.
 	 *
 	 * @return string
 	 */

WordPressVIPMinimum/Sniffs/Functions/DynamicCallsSniff.php

@@ -29,7 +29,7 @@ class DynamicCallsSniff extends Sniff {
 	/**
 	 * Functions that should not be called dynamically.
 	 *
-	 * @var array
+	 * @var array<string, bool>
 	 */
 	private $disallowed_functions = [
 		'assert'           => true,
@@ -48,7 +48,7 @@ class DynamicCallsSniff extends Sniff {
 	 *
 	 * Populated at run-time.
 	 *
-	 * @var array The key is the name of the variable, the value, its assigned value.
+	 * @var array<string, string> The key is the name of the variable, the value, its assigned value.
 	 */
 	private $variables_arr = [];
 
@@ -62,7 +62,7 @@ class DynamicCallsSniff extends Sniff {
 	/**
 	 * Returns the token types that this sniff is interested in.
 	 *
-	 * @return array(int)
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [ T_VARIABLE => T_VARIABLE ];

WordPressVIPMinimum/Sniffs/Functions/RestrictedFunctionsSniff.php

@@ -18,7 +18,7 @@ class RestrictedFunctionsSniff extends AbstractFunctionRestrictionsSniff {
 	/**
 	 * Groups of functions to restrict.
 	 *
-	 * @return array
+	 * @return array<string, array<string, string|array<string>|array<string, bool>>>
 	 */
 	public function getGroups() {
 

WordPressVIPMinimum/Sniffs/Functions/StripTagsSniff.php

@@ -26,10 +26,7 @@ class StripTagsSniff extends AbstractFunctionParameterSniff {
 	/**
 	 * Functions this sniff is looking for.
 	 *
-	 * @var array The only requirement for this array is that the top level
-	 *            array keys are the names of the functions you're looking for.
-	 *            Other than that, the array can have arbitrary content
-	 *            depending on your needs.
+	 * @var array<string, bool> Key is the function name, value irrelevant.
 	 */
 	protected $target_functions = [
 		'strip_tags' => true,

WordPressVIPMinimum/Sniffs/Hooks/AlwaysReturnInFilterSniff.php

@@ -27,7 +27,7 @@ class AlwaysReturnInFilterSniff extends Sniff {
 	/**
 	 * Returns the token types that this sniff is interested in.
 	 *
-	 * @return array(int)
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [ T_STRING ];

WordPressVIPMinimum/Sniffs/Hooks/PreGetPostsSniff.php

@@ -21,7 +21,7 @@ class PreGetPostsSniff extends Sniff {
 	/**
 	 * Returns the token types that this sniff is interested in.
 	 *
-	 * @return array(int)
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [ T_STRING ];

WordPressVIPMinimum/Sniffs/Hooks/RestrictedHooksSniff.php

@@ -26,10 +26,7 @@ class RestrictedHooksSniff extends AbstractFunctionParameterSniff {
 	/**
 	 * Functions this sniff is looking for.
 	 *
-	 * @var array The only requirement for this array is that the top level
-	 *            array keys are the names of the functions you're looking for.
-	 *            Other than that, the array can have arbitrary content
-	 *            depending on your needs.
+	 * @var array<string, bool> Key is the function name, value irrelevant.
 	 */
 	protected $target_functions = [
 		'add_filter' => true,
@@ -39,7 +36,7 @@ class RestrictedHooksSniff extends AbstractFunctionParameterSniff {
 	/**
 	 * List of restricted filters by groups.
 	 *
-	 * @var array
+	 * @var array<string, array<string, string|array<string>>>
 	 */
 	private $restricted_hook_groups = [
 		'upload_mimes' => [

WordPressVIPMinimum/Sniffs/JS/DangerouslySetInnerHTMLSniff.php

@@ -27,7 +27,7 @@ class DangerouslySetInnerHTMLSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [

WordPressVIPMinimum/Sniffs/JS/HTMLExecutingFunctionsSniff.php

@@ -24,7 +24,7 @@ class HTMLExecutingFunctionsSniff extends Sniff {
 	 * Value indicates whether the function's arg is the content to be inserted, or the target where the inserted
 	 * content is to be inserted before/after/replaced. For the latter, the content is in the preceding method's arg.
 	 *
-	 * @var array
+	 * @var array<string, string>
 	 */
 	public $HTMLExecutingFunctions = [
 		'after'        => 'content', // jQuery.
@@ -52,7 +52,7 @@ class HTMLExecutingFunctionsSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [

WordPressVIPMinimum/Sniffs/JS/InnerHTMLSniff.php

@@ -27,7 +27,7 @@ class InnerHTMLSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [

WordPressVIPMinimum/Sniffs/JS/StringConcatSniff.php

@@ -27,7 +27,7 @@ class StringConcatSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [
@@ -63,8 +63,8 @@ public function process_token( $stackPtr ) {
 	/**
 	 * Consolidated violation.
 	 *
-	 * @param int   $stackPtr The position of the current token in the stack passed in $tokens.
-	 * @param array $data     Replacements for the error message.
+	 * @param int           $stackPtr The position of the current token in the stack passed in $tokens.
+	 * @param array<string> $data     Replacements for the error message.
 	 *
 	 * @return void
 	 */

WordPressVIPMinimum/Sniffs/JS/StrippingTagsSniff.php

@@ -27,7 +27,7 @@ class StrippingTagsSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [

WordPressVIPMinimum/Sniffs/JS/WindowSniff.php

@@ -27,7 +27,7 @@ class WindowSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [
@@ -38,7 +38,7 @@ public function register() {
 	/**
 	 * List of window properties that need to be flagged.
 	 *
-	 * @var array
+	 * @var array<string, bool|array<string, bool>>
 	 */
 	private $windowProperties = [
 		'location' => [

WordPressVIPMinimum/Sniffs/Performance/CacheValueOverrideSniff.php

@@ -18,7 +18,7 @@ class CacheValueOverrideSniff extends Sniff {
 	/**
 	 * Returns the token types that this sniff is interested in.
 	 *
-	 * @return array(int)
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [ T_STRING ];

WordPressVIPMinimum/Sniffs/Performance/FetchingRemoteDataSniff.php

@@ -19,7 +19,7 @@ class FetchingRemoteDataSniff extends Sniff {
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * @return array
+	 * @return array<int|string>
 	 */
 	public function register() {
 		return [ T_STRING ];