From 641456d411af5ee00e18755480de991a11331f64 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 18 Jul 2025 00:35:25 +0200
Subject: [PATCH] Docs: improve type specificity

Not claiming completeness, but just fixing up some I ran into.
---
 WordPress/AbstractFunctionParameterSniff.php           | 10 +++++-----
 .../Sniffs/NamingConventions/ValidHookNameSniff.php    |  2 +-
 WordPress/Sniffs/PHP/IniSetSniff.php                   |  9 +++------
 WordPress/Sniffs/WP/DeprecatedParameterValuesSniff.php |  2 +-
 WordPress/Sniffs/WP/DeprecatedParametersSniff.php      |  2 +-
 5 files changed, 11 insertions(+), 14 deletions(-)

diff --git a/WordPress/AbstractFunctionParameterSniff.php b/WordPress/AbstractFunctionParameterSniff.php
index 4f5f64e47d..8f1fb1922c 100644
--- a/WordPress/AbstractFunctionParameterSniff.php
+++ b/WordPress/AbstractFunctionParameterSniff.php
@@ -32,17 +32,17 @@ abstract class AbstractFunctionParameterSniff extends AbstractFunctionRestrictio
 	/**
 	 * Functions this sniff is looking for. Should be defined in the child class.
 	 *
-	 * @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, mixed> 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.
 	 */
 	protected $target_functions = array();
 
 	/**
 	 * Groups of functions to restrict.
 	 *
-	 * @return array
+	 * @return array<string, array<string, array<string>>>
 	 */
 	public function getGroups() {
 		if ( empty( $this->target_functions ) ) {
diff --git a/WordPress/Sniffs/NamingConventions/ValidHookNameSniff.php b/WordPress/Sniffs/NamingConventions/ValidHookNameSniff.php
index 57ce70464a..55dee3bd65 100644
--- a/WordPress/Sniffs/NamingConventions/ValidHookNameSniff.php
+++ b/WordPress/Sniffs/NamingConventions/ValidHookNameSniff.php
@@ -69,7 +69,7 @@ class ValidHookNameSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @since 0.11.0
 	 *
-	 * @return array
+	 * @return array<string, array<string, array<string>>>
 	 */
 	public function getGroups() {
 		// Only retrieve functions which are not used for deprecated hooks.
diff --git a/WordPress/Sniffs/PHP/IniSetSniff.php b/WordPress/Sniffs/PHP/IniSetSniff.php
index b393fbc1ce..656c23b325 100644
--- a/WordPress/Sniffs/PHP/IniSetSniff.php
+++ b/WordPress/Sniffs/PHP/IniSetSniff.php
@@ -30,10 +30,7 @@ final class IniSetSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @since 2.1.0
 	 *
-	 * @var array Multidimensional array with parameter details.
-	 *     $target_functions = array(
-	 *         (string) Function name.
-	 *     );
+	 * @var array<string, true> Key is function name, value irrelevant.
 	 */
 	protected $target_functions = array(
 		'ini_set'   => true,
@@ -47,7 +44,7 @@ final class IniSetSniff extends AbstractFunctionParameterSniff {
 	 * @since 2.1.0
 	 * @since 3.0.0 Renamed from `$whitelisted_options` to `$safe_options`.
 	 *
-	 * @var array Multidimensional array with parameter details.
+	 * @var array<string, array<string, array<string>>> Multidimensional array with parameter details.
 	 *     $safe_options = array(
 	 *         (string) option name. = array(
 	 *             (string[]) 'valid_values' = array()
@@ -74,7 +71,7 @@ final class IniSetSniff extends AbstractFunctionParameterSniff {
 	 * @since 2.1.0
 	 * @since 3.0.0 Renamed from `$blacklisted_options` to `$disallowed_options`.
 	 *
-	 * @var array Multidimensional array with parameter details.
+	 * @var array<string, array<string, string|array<string>>> Multidimensional array with parameter details.
 	 *     $disallowed_options = array(
 	 *         (string) option name. = array(
 	 *             (string[]) 'invalid_values' = array()
diff --git a/WordPress/Sniffs/WP/DeprecatedParameterValuesSniff.php b/WordPress/Sniffs/WP/DeprecatedParameterValuesSniff.php
index ae4c3799fb..bfac0ee222 100644
--- a/WordPress/Sniffs/WP/DeprecatedParameterValuesSniff.php
+++ b/WordPress/Sniffs/WP/DeprecatedParameterValuesSniff.php
@@ -48,7 +48,7 @@ final class DeprecatedParameterValuesSniff extends AbstractFunctionParameterSnif
 	 * @since 3.0.0 The format of the value has changed to support function calls
 	 *              using named parameters.
 	 *
-	 * @var array Multidimensional array with parameter details.
+	 * @var array<string, array<int, array<string, mixed>>> Multidimensional array with parameter details.
 	 *     $target_functions = array(
 	 *         (string) Function name. => array(
 	 *             (int) Target parameter position, 1-based. => array(
diff --git a/WordPress/Sniffs/WP/DeprecatedParametersSniff.php b/WordPress/Sniffs/WP/DeprecatedParametersSniff.php
index 2675ecfae8..a76783c887 100644
--- a/WordPress/Sniffs/WP/DeprecatedParametersSniff.php
+++ b/WordPress/Sniffs/WP/DeprecatedParametersSniff.php
@@ -53,7 +53,7 @@ final class DeprecatedParametersSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @since 0.12.0
 	 *
-	 * @var array Multidimensional array with parameter details.
+	 * @var array<string, array<int, array<string, mixed>>> Multidimensional array with parameter details.
 	 *    $target_functions = array(
 	 *        (string) Function name. => array(
 	 *            (int) Target parameter position, 1-based. => array(