Description

This PR fixes critical documentation errors that would cause developers to write incorrect code when implementing the Abilities API.

Changes Made

1. ✅ Fixed Invalid Function Reference

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

Before:

The ability remains available for internal PHP usage via `wp_execute_ability()`.

After:

The ability remains available for internal PHP usage via `wp_get_ability()` and `$ability->execute()`.

Reason: The function wp_execute_ability() does not exist in the codebase. Verified by searching all files in includes/ directory. The correct pattern is documented in includes/abilities-api/class-wp-ability.php at line 595.

2. ✅ Fixed Incorrect Parameter Placement

Files:

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

Before:

wp_register_ability( 'my-plugin/ability', array(
    'label'               => __( 'Title', 'my-plugin' ),
    'description'         => __( 'Description.', 'my-plugin' ),
    'execute_callback'    => 'callback',
    'permission_callback' => '__return_true',
    'meta'                => array(
        'category'    => 'site-info',  // ❌ Wrong location
        'show_in_rest' => true,
    ),
) );

After:

wp_register_ability( 'my-plugin/ability', array(
    'label'               => __( 'Title', 'my-plugin' ),
    'description'         => __( 'Description.', 'my-plugin' ),
    'category'            => 'site-info',  // ✅ Correct location
    'execute_callback'    => 'callback',
    'permission_callback' => '__return_true',
    'meta'                => array(
        'show_in_rest' => true,
    ),
) );

Reason: According to the function signature in includes/abilities-api.php (line 237), category is a required top-level parameter, not part of the meta array. This is confirmed by the core implementation in includes/abilities/wp-core-abilities.php (line 89).

3. ✅ Fixed Incorrect Class Name

File: docs/hooks.md (line 26)

Before:

@param \WP_Abilities_Category_Registry $registry

After:

@param \WP_Ability_Categories_Registry $registry

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

Verification

Function Existence Check

All available global functions in includes/abilities-api.php:

• ✅ 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
• ❌ wp_execute_ability() - DOES NOT EXIST

Parameter Structure Check

Verified against:

• Function signature: includes/abilities-api.php (lines 232-277)
• Core implementation: includes/abilities/wp-core-abilities.php (lines 87-143)
• Class definition: includes/abilities-api/class-wp-ability.php (lines 213-260)

Impact

Before This PR ❌

Developers following the documentation would:

1. Get fatal errors calling non-existent wp_execute_ability()
2. Experience ability registration failures with category in wrong location
3. Have incorrect class name references in their code

After This PR ✅

Developers can:

1. Correctly execute abilities using wp_get_ability() and $ability->execute()
2. Successfully register abilities with proper parameter structure
3. Reference the correct class names in their implementations

Testing

• Verified all function names exist in codebase
• Checked actual implementation matches documented structure
• Cross-referenced with core ability examples
• Confirmed class names in actual class files

Checklist

• Documentation changes are accurate to codebase
• All code examples are tested against actual implementation
• Function references verified to exist
• Parameter structures match function signatures
• Class names verified in actual class files

Fixes: #139