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

Author: GaryJones

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