Docs: improve specificity

Miscellaneous other doc specificity fixes. Note: this doesn't fix everything throughout the codebase, but is an iteration to improve things nonetheless.
Automattic · Nov 8, 2024 · 97d83d5 · 97d83d5
1 parent b95dde7
commit 97d83d5
Show file tree

Hide file tree

Showing 19 changed files with 38 additions and 38 deletions.
diff --git a/WordPressVIPMinimum/Sniffs/Classes/DeclarationCompatibilitySniff.php b/WordPressVIPMinimum/Sniffs/Classes/DeclarationCompatibilitySniff.php
@@ -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 = [];

diff --git a/WordPressVIPMinimum/Sniffs/Classes/RestrictedExtendClassesSniff.php b/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 [

diff --git a/WordPressVIPMinimum/Sniffs/Constants/RestrictedConstantsSniff.php b/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',

diff --git a/WordPressVIPMinimum/Sniffs/Files/IncludingFileSniff.php b/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',

diff --git a/WordPressVIPMinimum/Sniffs/Files/IncludingNonPHPFileSniff.php b/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,

diff --git a/WordPressVIPMinimum/Sniffs/Functions/CheckReturnValueSniff.php b/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,
@@ -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
 	 */

diff --git a/WordPressVIPMinimum/Sniffs/Functions/DynamicCallsSniff.php b/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 = [];
 

diff --git a/WordPressVIPMinimum/Sniffs/Functions/RestrictedFunctionsSniff.php b/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() {
 

diff --git a/WordPressVIPMinimum/Sniffs/Hooks/RestrictedHooksSniff.php b/WordPressVIPMinimum/Sniffs/Hooks/RestrictedHooksSniff.php
@@ -36,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' => [

diff --git a/WordPressVIPMinimum/Sniffs/JS/HTMLExecutingFunctionsSniff.php b/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.

diff --git a/WordPressVIPMinimum/Sniffs/JS/StringConcatSniff.php b/WordPressVIPMinimum/Sniffs/JS/StringConcatSniff.php
@@ -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
 	 */

diff --git a/WordPressVIPMinimum/Sniffs/JS/WindowSniff.php b/WordPressVIPMinimum/Sniffs/JS/WindowSniff.php
@@ -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' => [

diff --git a/WordPressVIPMinimum/Sniffs/Performance/LowExpiryCacheTimeSniff.php b/WordPressVIPMinimum/Sniffs/Performance/LowExpiryCacheTimeSniff.php
@@ -41,7 +41,7 @@ class LowExpiryCacheTimeSniff extends AbstractFunctionParameterSniff {
 	/**
 	 * List of WP time constants, see https://codex.wordpress.org/Easier_Expression_of_Time_Constants.
 	 *
-	 * @var array
+	 * @var array<string, int>
 	 */
 	protected $wp_time_constants = [
 		'MINUTE_IN_SECONDS' => 60,

diff --git a/WordPressVIPMinimum/Sniffs/Performance/TaxonomyMetaInOptionsSniff.php b/WordPressVIPMinimum/Sniffs/Performance/TaxonomyMetaInOptionsSniff.php
@@ -19,7 +19,7 @@ class TaxonomyMetaInOptionsSniff extends Sniff {
 	/**
 	 * List of options_ functions
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	public $option_functions = [
 		'get_option',
@@ -31,7 +31,7 @@ class TaxonomyMetaInOptionsSniff extends Sniff {
 	/**
 	 * List of possible variable names holding term ID.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	public $taxonomy_term_patterns = [
 		'category_id',

diff --git a/WordPressVIPMinimum/Sniffs/Security/PHPFilterFunctionsSniff.php b/WordPressVIPMinimum/Sniffs/Security/PHPFilterFunctionsSniff.php
@@ -38,7 +38,7 @@ class PHPFilterFunctionsSniff extends AbstractFunctionParameterSniff {
 	/**
 	 * List of restricted filter names.
 	 *
-	 * @var array
+	 * @var array<string, bool>
 	 */
 	private $restricted_filters = [
 		'FILTER_DEFAULT'    => true,

diff --git a/WordPressVIPMinimum/Sniffs/Security/ProperEscapingFunctionSniff.php b/WordPressVIPMinimum/Sniffs/Security/ProperEscapingFunctionSniff.php
@@ -28,7 +28,7 @@ class ProperEscapingFunctionSniff extends Sniff {
 	/**
 	 * List of escaping functions which are being tested.
 	 *
-	 * @var array
+	 * @var array<string, string>
 	 */
 	protected $escaping_functions = [
 		'esc_url'    => 'url',
@@ -45,7 +45,7 @@ class ProperEscapingFunctionSniff extends Sniff {
 	/**
 	 * List of tokens we can skip.
 	 *
-	 * @var array
+	 * @var array<int|string, int|string>
 	 */
 	private $echo_or_concat_tokens =
 	[
@@ -63,7 +63,7 @@ class ProperEscapingFunctionSniff extends Sniff {
 	 *                   for public methods which extending sniffs may be
 	 *                   relying on.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	private $url_attrs = [
 		'href',
@@ -79,7 +79,7 @@ class ProperEscapingFunctionSniff extends Sniff {
 	 *                   for public methods which extending sniffs may be
 	 *                   relying on.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	private $attr_endings = [
 		'=',

diff --git a/WordPressVIPMinimum/Sniffs/UserExperience/AdminBarRemovalSniff.php b/WordPressVIPMinimum/Sniffs/UserExperience/AdminBarRemovalSniff.php
@@ -26,7 +26,7 @@ class AdminBarRemovalSniff extends AbstractFunctionParameterSniff {
 	/**
 	 * A list of tokenizers this sniff supports.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	public $supportedTokenizers = [
 		'PHP',
@@ -58,7 +58,7 @@ class AdminBarRemovalSniff extends AbstractFunctionParameterSniff {
 	/**
 	 * CSS properties this sniff is looking for.
 	 *
-	 * @var array
+	 * @var array<string, array<string, string|float>>
 	 */
 	protected $target_css_properties = [
 		'visibility' => [
@@ -78,7 +78,7 @@ class AdminBarRemovalSniff extends AbstractFunctionParameterSniff {
 	/**
 	 * CSS selectors this sniff is looking for.
 	 *
-	 * @var array
+	 * @var array<string>
 	 */
 	protected $target_css_selectors = [
 		'.show-admin-bar',
@@ -90,7 +90,7 @@ class AdminBarRemovalSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * Set from the register() method.
 	 *
-	 * @var array
+	 * @var array<int|string>
 	 */
 	private $string_tokens = [];
 

diff --git a/WordPressVIPMinimum/Sniffs/Variables/ServerVariablesSniff.php b/WordPressVIPMinimum/Sniffs/Variables/ServerVariablesSniff.php
@@ -18,7 +18,7 @@ class ServerVariablesSniff extends Sniff {
 	/**
 	 * List of restricted constant names.
 	 *
-	 * @var array
+	 * @var array<string, array<string, bool>>
 	 */
 	public $restrictedVariables = [
 		'authVariables'           => [

diff --git a/tests/RulesetTest.php b/tests/RulesetTest.php
@@ -28,7 +28,7 @@ class RulesetTest {
 	 *
 	 * This is the giant array in the ruleset-test.php files.
 	 *
-	 * @var array
+	 * @var array<string, array<int, int|array<string>>>
 	 */
 	public $expected = [];
 
@@ -82,8 +82,8 @@ class RulesetTest {
 	/**
 	 * Init the object by processing the test file.
 	 *
-	 * @param string $ruleset  Name of the ruleset e.g. WordPressVIPMinimum or WordPress-VIP-Go.
-	 * @param array  $expected The array of expected errors, warnings and messages.
+	 * @param string                                       $ruleset  Name of the ruleset e.g. WordPressVIPMinimum or WordPress-VIP-Go.
+	 * @param array<string, array<int, int|array<string>>> $expected The array of expected errors, warnings and messages.
 	 */
 	public function __construct( $ruleset, $expected = [] ) {
 		$this->ruleset  = $ruleset;