From b54d5925ce07025dc3acccb492ecabfea9583a9e Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Fri, 28 Feb 2020 12:29:53 +0000 Subject: [PATCH] Docs: Improve documentation for `WP_REST_Attachments_Controller`. This adds a missing DocBlock for `::register_routes()` and parameter descriptions for `::post_process_item()`. Includes minor documenation fixes in other REST API classes for consistency. Props dkarfa, mukesh27, SergeyBiryukov. Fixes #48841. git-svn-id: https://develop.svn.wordpress.org/trunk@47391 602fd350-edb4-49c9-b593-d223f7449a82 --- .../class-wp-rest-attachments-controller.php | 11 ++++++++-- .../class-wp-rest-autosaves-controller.php | 8 +++---- ...lass-wp-rest-block-renderer-controller.php | 2 ++ .../class-wp-rest-comments-controller.php | 2 ++ .../endpoints/class-wp-rest-controller.php | 22 ++++++++++--------- .../class-wp-rest-revisions-controller.php | 10 ++++----- 6 files changed, 34 insertions(+), 21 deletions(-) diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php index 2ce875440d..475d273f4f 100644 --- a/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php +++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php @@ -16,6 +16,13 @@ */ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller { + /** + * Registers the routes for attachments. + * + * @since 5.3.0 + * + * @see register_rest_route() + */ public function register_routes() { parent::register_routes(); register_rest_route( @@ -344,8 +351,8 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller { * * @since 5.3.0 * - * @param WP_REST_Request $request - * @return WP_REST_Response|WP_Error + * @param WP_REST_Request $request Full details about the request. + * @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure. */ public function post_process_item( $request ) { switch ( $request['action'] ) { diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-autosaves-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-autosaves-controller.php index 86c9cd45f6..245d2d4d5a 100644 --- a/src/wp-includes/rest-api/endpoints/class-wp-rest-autosaves-controller.php +++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-autosaves-controller.php @@ -73,7 +73,7 @@ class WP_REST_Autosaves_Controller extends WP_REST_Revisions_Controller { } /** - * Registers routes for autosaves. + * Registers the routes for autosaves. * * @since 5.0.0 * @@ -151,7 +151,7 @@ class WP_REST_Autosaves_Controller extends WP_REST_Revisions_Controller { * * @since 5.0.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return true|WP_Error True if the request has read access, WP_Error object otherwise. */ public function get_items_permissions_check( $request ) { @@ -249,7 +249,7 @@ class WP_REST_Autosaves_Controller extends WP_REST_Revisions_Controller { * * @since 5.0.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return WP_Post|WP_Error Revision post object if ID is valid, WP_Error otherwise. */ public function get_item( $request ) { @@ -284,7 +284,7 @@ class WP_REST_Autosaves_Controller extends WP_REST_Revisions_Controller { * * @since 5.0.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. */ public function get_items( $request ) { diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-block-renderer-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-block-renderer-controller.php index 96b4dfc068..94d349a1ba 100644 --- a/src/wp-includes/rest-api/endpoints/class-wp-rest-block-renderer-controller.php +++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-block-renderer-controller.php @@ -30,6 +30,8 @@ class WP_REST_Block_Renderer_Controller extends WP_REST_Controller { * Registers the necessary REST API routes, one for each dynamic block. * * @since 5.0.0 + * + * @see register_rest_route() */ public function register_routes() { $block_types = WP_Block_Type_Registry::get_instance()->get_all_registered(); diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php index c154c5550d..8d241d7c63 100644 --- a/src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php +++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php @@ -40,6 +40,8 @@ class WP_REST_Comments_Controller extends WP_REST_Controller { * Registers the routes for the objects of the controller. * * @since 4.7.0 + * + * @see register_rest_route() */ public function register_routes() { diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-controller.php index b32f012542..d9d60d2ee9 100644 --- a/src/wp-includes/rest-api/endpoints/class-wp-rest-controller.php +++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-controller.php @@ -42,6 +42,8 @@ abstract class WP_REST_Controller { * Registers the routes for the objects of the controller. * * @since 4.7.0 + * + * @see register_rest_route() */ public function register_routes() { _doing_it_wrong( @@ -57,7 +59,7 @@ abstract class WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return true|WP_Error True if the request has read access, WP_Error object otherwise. */ public function get_items_permissions_check( $request ) { @@ -74,7 +76,7 @@ abstract class WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. */ public function get_items( $request ) { @@ -91,7 +93,7 @@ abstract class WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise. */ public function get_item_permissions_check( $request ) { @@ -108,7 +110,7 @@ abstract class WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. */ public function get_item( $request ) { @@ -125,7 +127,7 @@ abstract class WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return true|WP_Error True if the request has access to create items, WP_Error object otherwise. */ public function create_item_permissions_check( $request ) { @@ -142,7 +144,7 @@ abstract class WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. */ public function create_item( $request ) { @@ -159,7 +161,7 @@ abstract class WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return true|WP_Error True if the request has access to update the item, WP_Error object otherwise. */ public function update_item_permissions_check( $request ) { @@ -176,7 +178,7 @@ abstract class WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. */ public function update_item( $request ) { @@ -193,7 +195,7 @@ abstract class WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return true|WP_Error True if the request has access to delete the item, WP_Error object otherwise. */ public function delete_item_permissions_check( $request ) { @@ -210,7 +212,7 @@ abstract class WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. */ public function delete_item( $request ) { diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php index f5fd0dda84..345dcd1596 100644 --- a/src/wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php +++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php @@ -61,7 +61,7 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller { } /** - * Registers routes for revisions based on post types supporting revisions. + * Registers the routes for revisions based on post types supporting revisions. * * @since 4.7.0 * @@ -160,7 +160,7 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return true|WP_Error True if the request has read access, WP_Error object otherwise. */ public function get_items_permissions_check( $request ) { @@ -214,7 +214,7 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. */ public function get_items( $request ) { @@ -363,7 +363,7 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return bool|WP_Error True if the request has read access for the item, WP_Error object otherwise. */ public function get_item_permissions_check( $request ) { @@ -375,7 +375,7 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller { * * @since 4.7.0 * - * @param WP_REST_Request $request Full data about the request. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. */ public function get_item( $request ) {