fix(docs): correct invalid function references and parameter placement (#140)

huzaifaalmesbah · gziolo · mindctrl · web-flow · commit cc030467fd9e · 2025-11-14T11:44:19.000Z
- Replace non-existent wp_execute_ability() with correct wp_get_ability() and -&gt;execute() pattern
- Move 'category' parameter from meta array to top-level args array in examples
- Fix class name from WP_Abilities_Category_Registry to WP_Ability_Categories_Registry

The documentation incorrectly referenced wp_execute_ability() which does not exist in the codebase (verified in includes/abilities-api.php lines 278-607). The correct approach is to use wp_get_ability() to retrieve the ability object, then call its execute() method (defined in includes/abilities-api/class-wp-ability.php line 595).

Additionally, code examples showed 'category' inside the meta array, but per the function signature (includes/abilities-api.php line 237) and core implementation (includes/abilities/wp-core-abilities.php line 89), category must be a top-level parameter.

Fixes documentation accuracy to match actual codebase implementation.

Co-authored-by: Greg Ziółkowski &lt;grzegorz@gziolo.pl&gt;

Co-authored-by: huzaifaalmesbah &lt;huzaifaalmesbah@git.wordpress.org&gt;
Co-authored-by: gziolo &lt;gziolo@git.wordpress.org&gt;
Co-authored-by: mindctrl &lt;mindctrl@git.wordpress.org&gt;
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -110,6 +110,7 @@ function my_plugin_register_abilities() {
     wp_register_ability( 'my-plugin/get-site-title', array(
         'label'               => __( 'Get Site Title', 'my-plugin' ),
         'description'         => __( 'Retrieves the title of the current WordPress site.', 'my-plugin' ),
+        'category'            => 'site-info',
         'input_schema'        => array(
             'type'                 => 'object',
             'properties'           => array(),
@@ -122,8 +123,8 @@ function my_plugin_register_abilities() {
         'execute_callback'    => 'my_plugin_get_site_title',
         'permission_callback' => '__return_true', // Everyone can access this
         'meta'                => array(
-            'category'    => 'site-info',
             'show_in_rest' => true, // Optional: expose via REST API
+        ),
     ) );
 }
 
diff --git a/docs/hooks.md b/docs/hooks.md
@@ -25,7 +25,7 @@ do_action( 'wp_abilities_api_categories_init', $registry );
 
 #### Parameters
 
-- `$registry` (`\WP_Abilities_Category_Registry`): The category registry instance.
+- `$registry` (`\WP_Ability_Categories_Registry`): The category registry instance.
 
 #### Usage Example
 
@@ -34,7 +34,7 @@ add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories'
 /**
  * Register custom ability categories.
  *
- * @param \WP_Abilities_Category_Registry $registry The category registry instance.
+ * @param \WP_Ability_Categories_Registry $registry The category registry instance.
  */
 function my_plugin_register_categories( $registry ) {
     wp_register_ability_category( 'ecommerce', array(
@@ -85,8 +85,8 @@ function my_plugin_register_abilities() {
         'execute_callback'    => 'my_plugin_get_site_title',
         'permission_callback' => '__return_true', // Everyone can access this
         'meta'                => array(
-            'category'    => 'site-info',
             'show_in_rest' => true, // Optional: expose via REST API
+        ),
     ) );
 }
 ```
diff --git a/docs/rest-api.md b/docs/rest-api.md
@@ -11,7 +11,7 @@ Access to all Abilities REST API endpoints requires an authenticated user (see t
 By default, registered abilities are **not** exposed via the REST API. You can control whether an individual ability appears in the REST API by using the `show_in_rest` meta when registering the ability:
 
 - `show_in_rest => true`: The ability is listed in REST API responses and can be executed via REST endpoints.
-- `show_in_rest => false` (default): The ability is hidden from REST API listings and cannot be executed via REST endpoints. The ability remains available for internal PHP usage via `wp_execute_ability()`.
+- `show_in_rest => false` (default): The ability is hidden from REST API listings and cannot be executed via REST endpoints. The ability remains available for internal PHP usage via `wp_get_ability()` and `$ability->execute()`.
 
 Abilities with meta `show_in_rest => false` will return a `rest_ability_not_found` error if accessed via REST endpoints.
 
