Skip to content

Commit bc7e060

Browse files
gziologziolo
committed
Expand PHPDoc for array params
1 parent 814bab6 commit bc7e060

File tree

5 files changed

+106
-15
lines changed

5 files changed

+106
-15
lines changed

‎src/wp-includes/abilities-api.php‎

Lines changed: 27 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,26 @@
2323
* @param string $name The name of the ability. The name must be a string containing a namespace
2424
* prefix, i.e. `my-plugin/my-ability`. It can only contain lowercase
2525
* alphanumeric characters, dashes and the forward slash.
26-
* @param array<string,mixed> $args An associative array of arguments for the ability. This should include
27-
* `label`, `description`, `category`, `input_schema`, `output_schema`, `execute_callback`,
28-
* `permission_callback`, `meta`, and `ability_class`.
26+
* @param array<string,mixed> $args {
27+
* An associative array of arguments for the ability.
28+
*
29+
* @type string $label The human-readable label for the ability.
30+
* @type string $description A detailed description of what the ability does.
31+
* @type string $category The category slug this ability belongs to.
32+
* @type callable $execute_callback A callback function to execute when the ability is invoked.
33+
* Receives optional mixed input and returns mixed result or WP_Error.
34+
* @type callable $permission_callback A callback function to check permissions before execution.
35+
* Receives optional mixed input and returns bool or WP_Error.
36+
* @type array<string,mixed> $input_schema Optional. JSON Schema definition for the ability's input.
37+
* @type array<string,mixed> $output_schema Optional. JSON Schema definition for the ability's output.
38+
* @type array<string,mixed> $meta {
39+
* Optional. Additional metadata for the ability.
40+
*
41+
* @type array<string,bool|string> $annotations Optional. Annotation metadata for the ability.
42+
* @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
43+
* }
44+
* @type string $ability_class Optional. Custom class to instantiate instead of WP_Ability.
45+
* }
2946
* @return WP_Ability|null An instance of registered ability on success, null on failure.
3047
*
3148
* @phpstan-param array{
@@ -113,8 +130,13 @@ function wp_get_abilities(): array {
113130
*
114131
* @param string $slug The unique slug for the category. Must contain only lowercase
115132
* alphanumeric characters and dashes.
116-
* @param array<string,mixed> $args An associative array of arguments for the category. This should
117-
* include `label`, `description`, and optionally `meta`.
133+
* @param array<string,mixed> $args {
134+
* An associative array of arguments for the category.
135+
*
136+
* @type string $label The human-readable label for the category.
137+
* @type string $description A description of the category.
138+
* @type array<string,mixed> $meta Optional. Additional metadata for the category.
139+
* }
118140
* @return WP_Ability_Category|null The registered category instance on success, null on failure.
119141
*
120142
* @phpstan-param array{

‎src/wp-includes/abilities-api/class-wp-abilities-category-registry.php‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,13 @@ final class WP_Abilities_Category_Registry {
4545
*
4646
* @param string $slug The unique slug for the category. Must contain only lowercase
4747
* alphanumeric characters and dashes.
48-
* @param array<string,mixed> $args An associative array of arguments for the category. See wp_register_ability_category() for
49-
* details.
48+
* @param array<string,mixed> $args {
49+
* An associative array of arguments for the category.
50+
*
51+
* @type string $label The human-readable label for the category.
52+
* @type string $description A description of the category.
53+
* @type array<string,mixed> $meta Optional. Additional metadata for the category.
54+
* }
5055
* @return WP_Ability_Category|null The registered category instance on success, null on failure.
5156
*
5257
* @phpstan-param array{
@@ -95,7 +100,13 @@ public function register( string $slug, array $args ): ?WP_Ability_Category {
95100
*
96101
* @since 6.9.0
97102
*
98-
* @param array<string,mixed> $args The arguments used to instantiate the category.
103+
* @param array<string,mixed> $args {
104+
* The arguments used to instantiate the category.
105+
*
106+
* @type string $label The human-readable label for the category.
107+
* @type string $description A description of the category.
108+
* @type array<string,mixed> $meta Optional. Additional metadata for the category.
109+
* }
99110
* @param string $slug The slug of the category.
100111
*/
101112
$args = apply_filters( 'register_ability_category_args', $args, $slug );

‎src/wp-includes/abilities-api/class-wp-abilities-registry.php‎

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,26 @@ final class WP_Abilities_Registry {
4646
* @param string $name The name of the ability. The name must be a string containing a namespace
4747
* prefix, i.e. `my-plugin/my-ability`. It can only contain lowercase
4848
* alphanumeric characters, dashes and the forward slash.
49-
* @param array<string,mixed> $args An associative array of arguments for the ability. See wp_register_ability() for
50-
* details.
49+
* @param array<string,mixed> $args {
50+
* An associative array of arguments for the ability.
51+
*
52+
* @type string $label The human-readable label for the ability.
53+
* @type string $description A detailed description of what the ability does.
54+
* @type string $category The category slug this ability belongs to.
55+
* @type callable $execute_callback A callback function to execute when the ability is invoked.
56+
* Receives optional mixed input and returns mixed result or WP_Error.
57+
* @type callable $permission_callback A callback function to check permissions before execution.
58+
* Receives optional mixed input and returns bool or WP_Error.
59+
* @type array<string,mixed> $input_schema Optional. JSON Schema definition for the ability's input.
60+
* @type array<string,mixed> $output_schema Optional. JSON Schema definition for the ability's output.
61+
* @type array<string,mixed> $meta {
62+
* Optional. Additional metadata for the ability.
63+
*
64+
* @type array<string,bool|string> $annotations Optional. Annotation metadata for the ability.
65+
* @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
66+
* }
67+
* @type string $ability_class Optional. Custom class to instantiate instead of WP_Ability.
68+
* }
5169
* @return WP_Ability|null The registered ability instance on success, null on failure.
5270
*
5371
* @phpstan-param array{
@@ -94,7 +112,25 @@ public function register( string $name, array $args ): ?WP_Ability {
94112
*
95113
* @since 6.9.0
96114
*
97-
* @param array<string,mixed> $args The arguments used to instantiate the ability.
115+
* @param array<string,mixed> $args {
116+
* An associative array of arguments for the ability.
117+
*
118+
* @type string $label The human-readable label for the ability.
119+
* @type string $description A detailed description of what the ability does.
120+
* @type string $category The category slug this ability belongs to.
121+
* @type callable $execute_callback A callback function to execute when the ability is invoked.
122+
* Receives optional mixed input and returns mixed result or WP_Error.
123+
* @type callable $permission_callback A callback function to check permissions before execution.
124+
* Receives optional mixed input and returns bool or WP_Error.
125+
* @type array<string,mixed> $input_schema Optional. JSON Schema definition for the ability's input.
126+
* @type array<string,mixed> $output_schema Optional. JSON Schema definition for the ability's output.
127+
* @type array<string,mixed> $meta {
128+
* Optional. Additional metadata for the ability.
129+
*
130+
* @type array<string,bool|string> $annotations Optional. Annotation metadata for the ability.
131+
* @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
132+
* }
133+
* }
98134
* @param string $name The name of the ability, with its namespace.
99135
*/
100136
$args = apply_filters( 'register_ability_args', $args, $name );

‎src/wp-includes/abilities-api/class-wp-ability-category.php‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,13 @@ final class WP_Ability_Category {
6464
* @see wp_register_ability_category()
6565
*
6666
* @param string $slug The unique slug for the category.
67-
* @param array<string,mixed> $args An associative array of arguments for the category.
67+
* @param array<string,mixed> $args {
68+
* An associative array of arguments for the category.
69+
*
70+
* @type string $label The human-readable label for the category.
71+
* @type string $description A description of the category.
72+
* @type array<string,mixed> $meta Optional. Additional metadata for the category.
73+
* }
6874
*/
6975
public function __construct( string $slug, array $args ) {
7076
if ( empty( $slug ) ) {

‎src/wp-includes/abilities-api/class-wp-ability.php‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -137,9 +137,25 @@ class WP_Ability {
137137
* @see wp_register_ability()
138138
*
139139
* @param string $name The name of the ability, with its namespace.
140-
* @param array<string,mixed> $args An associative array of arguments for the ability. This should include:
141-
* `label`, `description`, `category`, `input_schema`, `output_schema`,
142-
* `execute_callback`, `permission_callback` and `meta`
140+
* @param array<string,mixed> $args {
141+
* An associative array of arguments for the ability.
142+
*
143+
* @type string $label The human-readable label for the ability.
144+
* @type string $description A detailed description of what the ability does.
145+
* @type string $category The category slug this ability belongs to.
146+
* @type callable $execute_callback A callback function to execute when the ability is invoked.
147+
* Receives optional mixed input and returns mixed result or WP_Error.
148+
* @type callable $permission_callback A callback function to check permissions before execution.
149+
* Receives optional mixed input and returns bool or WP_Error.
150+
* @type array<string,mixed> $input_schema Optional. JSON Schema definition for the ability's input.
151+
* @type array<string,mixed> $output_schema Optional. JSON Schema definition for the ability's output.
152+
* @type array<string,mixed> $meta {
153+
* Optional. Additional metadata for the ability.
154+
*
155+
* @type array<string,bool|string> $annotations Optional. Annotation metadata for the ability.
156+
* @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
157+
* }
158+
* }
143159
*/
144160
public function __construct( string $name, array $args ) {
145161
$this->name = $name;

0 commit comments

Comments
 (0)