From 4b2c039d669707d735185035f069badaa40af2a6 Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Mon, 17 Nov 2025 13:04:51 +0600 Subject: [PATCH] docs: add missing @return tags and improve return descriptions - Add @return void tags to all register_routes() methods across REST controllers - Enhance boolean return descriptions to cover both true/false cases - Clarify mixed return types to explain when null is returned - Fix spacing in array type hints (array) Per WordPress Inline Documentation Standards, all methods must document their return types, including void. Boolean returns should describe both success and failure cases. Mixed types should clarify all possible return values including null. Affected files: - includes/rest-api/class-wp-rest-abilities-init.php - includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php - includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php - includes/rest-api/endpoints/class-wp-rest-abilities-v1-run-controller.php - includes/abilities-api/class-wp-ability-category.php --- includes/abilities-api/class-wp-ability-category.php | 5 +++-- includes/rest-api/class-wp-rest-abilities-init.php | 1 + .../class-wp-rest-abilities-v1-categories-controller.php | 5 +++-- .../endpoints/class-wp-rest-abilities-v1-list-controller.php | 5 +++-- .../endpoints/class-wp-rest-abilities-v1-run-controller.php | 3 ++- 5 files changed, 12 insertions(+), 7 deletions(-) diff --git a/includes/abilities-api/class-wp-ability-category.php b/includes/abilities-api/class-wp-ability-category.php index 957ce5e..1a60a37 100644 --- a/includes/abilities-api/class-wp-ability-category.php +++ b/includes/abilities-api/class-wp-ability-category.php @@ -2,7 +2,8 @@ /** * Abilities API * - * Defines WP_Ability_Category class. + * Defines the WP_Ability_Category class for organizing and categorizing + * related abilities within the Abilities API. * * @package WordPress * @subpackage Abilities API @@ -186,7 +187,7 @@ public function get_description(): string { * * @since 6.9.0 * - * @return array The metadata for the ability category. + * @return array The metadata for the ability category. */ public function get_meta(): array { return $this->meta; diff --git a/includes/rest-api/class-wp-rest-abilities-init.php b/includes/rest-api/class-wp-rest-abilities-init.php index be25ca9..8f6f3f7 100644 --- a/includes/rest-api/class-wp-rest-abilities-init.php +++ b/includes/rest-api/class-wp-rest-abilities-init.php @@ -23,6 +23,7 @@ class WP_REST_Abilities_Init { * * @param WP_REST_Server|null $rest_server Optional. The REST server to register routes with. Default null, which * will use the main REST server instance. + * @return void */ public static function register_routes( $rest_server = null ): void { if ( ! $rest_server instanceof WP_REST_Server ) { diff --git a/includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php b/includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php index 2156109..a0e6bf4 100644 --- a/includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php +++ b/includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php @@ -40,6 +40,7 @@ class WP_REST_Abilities_V1_Categories_Controller extends WP_REST_Controller { * @since 6.9.0 * * @see register_rest_route() + * @return void */ public function register_routes(): void { register_rest_route( @@ -161,7 +162,7 @@ public function get_item( $request ) { * @since 6.9.0 * * @param WP_REST_Request $request Full details about the request. - * @return bool True if the request has read access. + * @return bool True if the request has read access, false otherwise. */ public function get_items_permissions_check( $request ) { return current_user_can( 'read' ); @@ -173,7 +174,7 @@ public function get_items_permissions_check( $request ) { * @since 6.9.0 * * @param WP_REST_Request $request Full details about the request. - * @return bool True if the request has read access. + * @return bool True if the request has read access, false otherwise. */ public function get_item_permissions_check( $request ) { return current_user_can( 'read' ); diff --git a/includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php b/includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php index 4f59d90..bc5f350 100644 --- a/includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php +++ b/includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php @@ -40,6 +40,7 @@ class WP_REST_Abilities_V1_List_Controller extends WP_REST_Controller { * @since 6.9.0 * * @see register_rest_route() + * @return void */ public function register_routes(): void { register_rest_route( @@ -176,7 +177,7 @@ public function get_item( $request ) { * @since 6.9.0 * * @param WP_REST_Request $request Full details about the request. - * @return bool True if the request has read access. + * @return bool True if the request has read access, false otherwise. */ public function get_items_permissions_check( $request ) { return current_user_can( 'read' ); @@ -188,7 +189,7 @@ public function get_items_permissions_check( $request ) { * @since 6.9.0 * * @param WP_REST_Request $request Full details about the request. - * @return bool True if the request has read access. + * @return bool True if the request has read access, false otherwise. */ public function get_item_permissions_check( $request ) { return current_user_can( 'read' ); diff --git a/includes/rest-api/endpoints/class-wp-rest-abilities-v1-run-controller.php b/includes/rest-api/endpoints/class-wp-rest-abilities-v1-run-controller.php index 36766a2..43b71f0 100644 --- a/includes/rest-api/endpoints/class-wp-rest-abilities-v1-run-controller.php +++ b/includes/rest-api/endpoints/class-wp-rest-abilities-v1-run-controller.php @@ -40,6 +40,7 @@ class WP_REST_Abilities_V1_Run_Controller extends WP_REST_Controller { * @since 6.9.0 * * @see register_rest_route() + * @return void */ public function register_routes(): void { register_rest_route( @@ -188,7 +189,7 @@ public function check_ability_permissions( $request ) { * @since 6.9.0 * * @param WP_REST_Request $request The request object. - * @return mixed|null The input parameters. + * @return mixed|null The input parameters, or null if not provided. */ private function get_input_from_request( $request ) { if ( in_array( $request->get_method(), array( 'GET', 'DELETE' ), true ) ) {