Description

The documentation contains references to a non-existent function wp_execute_ability() and shows incorrect placement of the category parameter within the meta array instead of as a top-level parameter.

Issues Found

1. Invalid Function Reference: wp_execute_ability()

Location: docs/rest-api.md (line 14)

Problem: Documentation references wp_execute_ability() which does not exist in the codebase.

Evidence: Searching the entire includes/ directory shows no such function exists. The available functions in includes/abilities-api.php are:

• wp_register_ability() (line 278)
• wp_unregister_ability() (line 324)
• wp_has_ability() (line 357)
• wp_get_ability() (line 389)
• wp_get_abilities() (line 419)
• wp_register_ability_category() (line 467)
• wp_unregister_ability_category() (line 512)
• wp_has_ability_category() (line 544)
• wp_get_ability_category() (line 576)
• wp_get_ability_categories() (line 607)

Correct approach:

$ability = wp_get_ability( 'ability-name' );
$result = $ability->execute();

Reference: The execute() method is defined in includes/abilities-api/class-wp-ability.php at line 595.

2. Incorrect Parameter Placement: category

Locations:

• docs/getting-started.md (lines 110-127)
• docs/hooks.md (lines 72-91)

Problem: The category parameter is shown inside the meta array, but it should be a top-level parameter of the $args array.

Evidence: According to the function documentation in includes/abilities-api.php (lines 232-239):

 * @param array<string, mixed> $args {
 *     An associative array of arguments for configuring the ability.
 *
 *     @type string               $label               Required. The human-readable label for the ability.
 *     @type string               $description         Required. A detailed description of what the ability does
 *                                                     and when it should be used.
 *     @type string               $category            Required. The ability category slug this ability belongs to.

And actual implementation in core abilities (includes/abilities/wp-core-abilities.php, lines 87-143) shows:

wp_register_ability(
    'core/get-site-info',
    array(
        'label'               => __( 'Get Site Information' ),
        'description'         => __( 'Returns site information...' ),
        'category'            => $category_site,  // ← Top-level parameter
        'input_schema'        => array( /* ... */ ),
        'output_schema'       => array( /* ... */ ),
        'execute_callback'    => static function ( $input = array() ) { /* ... */ },
        'permission_callback' => static function (): bool { /* ... */ },
        'meta'                => array(  // ← meta is separate
            'annotations'  => array( /* ... */ ),
            'show_in_rest' => true,
        ),
    )
);

3. Incorrect Class Name

Location: docs/hooks.md (line 26)

Problem: Documentation references \WP_Abilities_Category_Registry (singular "Abilities_Category")

Evidence: The actual class name is WP_Ability_Categories_Registry (plural "Categories") as defined in includes/abilities-api/class-wp-ability-categories-registry.php (line 18).

Impact

• Developers following the documentation will:
  1. Try to call a non-existent function causing fatal errors
  2. Place the category parameter in the wrong location causing registration failures
  3. Reference an incorrect class name in their code comments

Proposed Solution

1. Replace wp_execute_ability() references with wp_get_ability() and $ability->execute()
2. Move category parameter to the top-level of the $args array in all examples
3. Correct the class name from WP_Abilities_Category_Registry to WP_Ability_Categories_Registry

Files to Update

• docs/rest-api.md
• docs/getting-started.md
• docs/hooks.md