REST API: Corrections and improvements to docblocks for REST API filters.

See #51800


git-svn-id: https://develop.svn.wordpress.org/trunk@49955 602fd350-edb4-49c9-b593-d223f7449a82

12 files changed, 49 insertions, 41 deletions

diff --git a/src/wp-includes/rest-api/class-wp-rest-request.php b/src/wp-includes/rest-api/class-wp-rest-request.php
index 94a0a28790..e972c5fa25 100644
--- a/src/wp-includes/rest-api/class-wp-rest-request.php
+++ b/src/wp-includes/rest-api/class-wp-rest-request.php
@@ -339,7 +339,7 @@ class WP_REST_Request implements ArrayAccess {
 	/**
 	 * Retrieves the parameter priority order.
 	 *
-	 * Used when checking parameters in get_param().
+	 * Used when checking parameters in WP_REST_Request::get_param().
 	 *
 	 * @since 4.4.0
 	 *
@@ -371,10 +371,10 @@ class WP_REST_Request implements ArrayAccess {
 		$order[] = 'defaults';
 
 		/**
-		 * Filters the parameter order.
+		 * Filters the parameter priority order for a REST API request.
 		 *
-		 * The order affects which parameters are checked when using get_param() and family.
-		 * This acts similarly to PHP's `request_order` setting.
+		 * The order affects which parameters are checked when using WP_REST_Request::get_param()
+		 * and family. This acts similarly to PHP's `request_order` setting.
 		 *
 		 * @since 4.4.0
 		 *
@@ -1035,7 +1035,7 @@ class WP_REST_Request implements ArrayAccess {
 		}
 
 		/**
-		 * Filters the request generated from a URL.
+		 * Filters the REST API request generated from a URL.
 		 *
 		 * @since 4.5.0
 		 *
diff --git a/src/wp-includes/rest-api/class-wp-rest-server.php b/src/wp-includes/rest-api/class-wp-rest-server.php
index 5cf1353f9a..d7f8ae9a41 100644
--- a/src/wp-includes/rest-api/class-wp-rest-server.php
+++ b/src/wp-includes/rest-api/class-wp-rest-server.php
@@ -162,7 +162,7 @@ class WP_REST_Server {
 	 */
 	public function check_authentication() {
 		/**
-		 * Filters REST authentication errors.
+		 * Filters REST API authentication errors.
 		 *
 		 * This is used to pass a WP_Error from an authentication method back to
 		 * the API.
@@ -310,11 +310,11 @@ class WP_REST_Server {
 		$expose_headers = array( 'X-WP-Total', 'X-WP-TotalPages', 'Link' );
 
 		/**
-		 * Filters the list of response headers that are exposed to CORS requests.
+		 * Filters the list of response headers that are exposed to REST API CORS requests.
 		 *
 		 * @since 5.5.0
 		 *
-		 * @param string[] $expose_headers The list of headers to expose.
+		 * @param string[] $expose_headers The list of response headers to expose.
 		 */
 		$expose_headers = apply_filters( 'rest_exposed_cors_headers', $expose_headers );
 
@@ -329,7 +329,7 @@ class WP_REST_Server {
 		);
 
 		/**
-		 * Filters the list of request headers that are allowed for CORS requests.
+		 * Filters the list of request headers that are allowed for REST API CORS requests.
 		 *
 		 * The allowed headers are passed to the browser to specify which
 		 * headers can be passed to the REST API. By default, we allow the
@@ -338,14 +338,14 @@ class WP_REST_Server {
 		 *
 		 * @since 5.5.0
 		 *
-		 * @param string[] $allow_headers The list of headers to allow.
+		 * @param string[] $allow_headers The list of request headers to allow.
 		 */
 		$allow_headers = apply_filters( 'rest_allowed_cors_headers', $allow_headers );
 
 		$this->send_header( 'Access-Control-Allow-Headers', implode( ', ', $allow_headers ) );
 
 		/**
-		 * Send nocache headers on authenticated requests.
+		 * Filters whether to send nocache headers on a REST API request.
 		 *
 		 * @since 4.4.0
 		 *
@@ -384,11 +384,11 @@ class WP_REST_Server {
 		);
 
 		/**
-		 * Filters whether jsonp is enabled.
+		 * Filters whether JSONP is enabled for the REST API.
 		 *
 		 * @since 4.4.0
 		 *
-		 * @param bool $jsonp_enabled Whether jsonp is enabled. Default true.
+		 * @param bool $jsonp_enabled Whether JSONP is enabled. Default true.
 		 */
 		$jsonp_enabled = apply_filters( 'rest_jsonp_enabled', true );
 
@@ -768,11 +768,17 @@ class WP_REST_Server {
 		);
 
 		/**
-		 * Filters the enveloped form of a response.
+		 * Filters the enveloped form of a REST API response.
 		 *
 		 * @since 4.4.0
 		 *
-		 * @param array            $envelope Envelope data.
+		 * @param array            $envelope {
+		 *     Envelope data.
+		 *
+		 *     @type array $body    Response data.
+		 *     @type int   $status  The 3-digit HTTP status code.
+		 *     @type array $headers Map of header name to header value.
+		 * }
 		 * @param WP_REST_Response $response Original response data.
 		 */
 		$envelope = apply_filters( 'rest_envelope_response', $envelope, $response );
@@ -857,7 +863,7 @@ class WP_REST_Server {
 		}
 
 		/**
-		 * Filters the array of available endpoints.
+		 * Filters the array of available REST API endpoints.
 		 *
 		 * @since 4.4.0
 		 *
@@ -957,7 +963,7 @@ class WP_REST_Server {
 	 */
 	public function dispatch( $request ) {
 		/**
-		 * Filters the pre-calculated result of a REST dispatch request.
+		 * Filters the pre-calculated result of a REST API dispatch request.
 		 *
 		 * Allow hijacking the request before dispatching by returning a non-empty. The returned value
 		 * will be used to serve the request instead.
@@ -1116,7 +1122,8 @@ class WP_REST_Server {
 		 *
 		 * @since 4.7.0
 		 *
-		 * @param WP_REST_Response|WP_HTTP_Response|WP_Error|mixed $response Result to send to the client. Usually a WP_REST_Response or WP_Error.
+		 * @param WP_REST_Response|WP_HTTP_Response|WP_Error|mixed $response Result to send to the client.
+		 *                                                                   Usually a WP_REST_Response or WP_Error.
 		 * @param array                                            $handler  Route handler used for the request.
 		 * @param WP_REST_Request                                  $request  Request used to generate the response.
 		 */
@@ -1139,7 +1146,7 @@ class WP_REST_Server {
 
 		if ( ! is_wp_error( $response ) ) {
 			/**
-			 * Filters the REST dispatch request result.
+			 * Filters the REST API dispatch request result.
 			 *
 			 * Allow plugins to override dispatching the request.
 			 *
@@ -1177,7 +1184,8 @@ class WP_REST_Server {
 		 *
 		 * @since 4.7.0
 		 *
-		 * @param WP_REST_Response|WP_HTTP_Response|WP_Error|mixed $response Result to send to the client. Usually a WP_REST_Response or WP_Error.
+		 * @param WP_REST_Response|WP_HTTP_Response|WP_Error|mixed $response Result to send to the client.
+		 *                                                                   Usually a WP_REST_Response or WP_Error.
 		 * @param array                                            $handler  Route handler used for the request.
 		 * @param WP_REST_Request                                  $request  Request used to generate the response.
 		 */
@@ -1323,7 +1331,7 @@ class WP_REST_Server {
 		$response->add_link( 'up', rest_url( '/' ) );
 
 		/**
-		 * Filters the namespace index data.
+		 * Filters the REST API namespace index data.
 		 *
 		 * This typically is just the route data for the namespace, but you can
 		 * add any data you'd like here.
@@ -1356,7 +1364,7 @@ class WP_REST_Server {
 			}
 
 			/**
-			 * Filters the REST endpoint data.
+			 * Filters the REST API endpoint data.
 			 *
 			 * @since 4.4.0
 			 *
@@ -1366,7 +1374,7 @@ class WP_REST_Server {
 		}
 
 		/**
-		 * Filters the publicly-visible data for routes.
+		 * Filters the publicly-visible data for REST API routes.
 		 *
 		 * This data is exposed on indexes and can be used by clients or
 		 * developers to investigate the site and find out how to use it. It
@@ -1466,7 +1474,7 @@ class WP_REST_Server {
 	 */
 	protected function get_max_batch_size() {
 		/**
-		 * Filters the maximum number of requests that can be included in a batch.
+		 * Filters the maximum number of REST API requests that can be included in a batch.
 		 *
 		 * @since 5.6.0
 		 *
diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php
index c67bdb525d..7fd4e4f8f9 100644
--- a/src/wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php
+++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php
@@ -313,7 +313,7 @@ class WP_REST_Block_Directory_Controller extends WP_REST_Controller {
 		unset( $query_params['search'] );
 
 		/**
-		 * Filters collection parameters for the block directory controller.
+		 * Filters REST API collection parameters for the block directory controller.
 		 *
 		 * @since 5.5.0
 		 *
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 0161d2d670..9f36e3b386 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
@@ -449,7 +449,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 			}
 
 			/**
-			 * Filters whether comments can be created without authentication.
+			 * Filters whether comments can be created via the REST API without authentication.
 			 *
 			 * Enables creating comments for anonymous users.
 			 *
@@ -955,14 +955,14 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		$force = isset( $request['force'] ) ? (bool) $request['force'] : false;
 
 		/**
-		 * Filters whether a comment can be trashed.
+		 * Filters whether a comment can be trashed via the REST API.
 		 *
-		 * Return false to disable Trash support for the post.
+		 * Return false to disable trash support for the comment.
 		 *
 		 * @since 4.7.0
 		 *
-		 * @param bool    $supports_trash Whether the post type support trashing.
-		 * @param WP_Post $comment        The comment object being considered for trashing support.
+		 * @param bool       $supports_trash Whether the comment supports trashing.
+		 * @param WP_Comment $comment        The comment object being considered for trashing support.
 		 */
 		$supports_trash = apply_filters( 'rest_comment_trashable', ( EMPTY_TRASH_DAYS > 0 ), $comment );
 
@@ -1351,7 +1351,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		}
 
 		/**
-		 * Filters a comment after it is prepared for the database.
+		 * Filters a comment added via the REST API after it is prepared for insertion into the database.
 		 *
 		 * Allows modification of the comment right after it is prepared for the database.
 		 *
@@ -1674,7 +1674,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		);
 
 		/**
-		 * Filters collection parameters for the comments controller.
+		 * Filters REST API collection parameters for the comments controller.
 		 *
 		 * This filter registers the collection parameter, but does not map the
 		 * collection parameter to an internal WP_Comment_Query parameter. Use the
diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php
index c4155ad63d..7cb895670a 100644
--- a/src/wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php
+++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php
@@ -586,7 +586,7 @@ class WP_REST_Plugins_Controller extends WP_REST_Controller {
 		$response->add_links( $this->prepare_links( $item ) );
 
 		/**
-		 * Filters the plugin data for a response.
+		 * Filters plugin data for a REST API response.
 		 *
 		 * @since 5.5.0
 		 *
diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php
index fede70d6cf..25223386e4 100644
--- a/src/wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php
+++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php
@@ -268,14 +268,14 @@ class WP_REST_Post_Statuses_Controller extends WP_REST_Controller {
 		}
 
 		/**
-		 * Filters a status returned from the REST API.
+		 * Filters a post status returned from the REST API.
 		 *
 		 * Allows modification of the status data right before it is returned.
 		 *
 		 * @since 4.7.0
 		 *
 		 * @param WP_REST_Response $response The response object.
-		 * @param object           $status   The original status object.
+		 * @param object           $status   The original post status object.
 		 * @param WP_REST_Request  $request  Request used to generate the response.
 		 */
 		return apply_filters( 'rest_prepare_status', $response, $status, $request );
diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php
index 5bee39b1a8..6b41725d8c 100644
--- a/src/wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php
+++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php
@@ -154,7 +154,7 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
 			}
 
 			/**
-			 * Filters whether to preempt a setting value update.
+			 * Filters whether to preempt a setting value update via the REST API.
 			 *
 			 * Allows hijacking the setting update logic and overriding the built-in behavior by
 			 * returning true.
diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php
index 1e9dd5e961..212288d476 100644
--- a/src/wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php
+++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php
@@ -580,7 +580,7 @@ class WP_REST_Themes_Controller extends WP_REST_Controller {
 		);
 
 		/**
-		 * Filters collection parameters for the themes controller.
+		 * Filters REST API collection parameters for the themes controller.
 		 *
 		 * @since 5.0.0
 		 *
diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php
index d0f23e9124..58071fde6e 100644
--- a/src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php
+++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php
@@ -1559,7 +1559,7 @@ class WP_REST_Users_Controller extends WP_REST_Controller {
 		);
 
 		/**
-		 * Filters collection parameters for the users controller.
+		 * Filters REST API collection parameters for the users controller.
 		 *
 		 * This filter registers the collection parameter, but does not map the
 		 * collection parameter to an internal WP_User_Query parameter.  Use the
diff --git a/src/wp-includes/rest-api/search/class-wp-rest-post-format-search-handler.php b/src/wp-includes/rest-api/search/class-wp-rest-post-format-search-handler.php
index ced445ed56..b2192816c7 100644
--- a/src/wp-includes/rest-api/search/class-wp-rest-post-format-search-handler.php
+++ b/src/wp-includes/rest-api/search/class-wp-rest-post-format-search-handler.php
@@ -46,7 +46,7 @@ class WP_REST_Post_Format_Search_Handler extends WP_REST_Search_Handler {
 		}
 
 		/**
-		 * Filters the query arguments for a search request.
+		 * Filters the query arguments for a REST API search request.
 		 *
 		 * Enables adding extra arguments or setting defaults for a post format search request.
 		 *
diff --git a/src/wp-includes/rest-api/search/class-wp-rest-post-search-handler.php b/src/wp-includes/rest-api/search/class-wp-rest-post-search-handler.php
index 53879ed303..0e94f57bda 100644
--- a/src/wp-includes/rest-api/search/class-wp-rest-post-search-handler.php
+++ b/src/wp-includes/rest-api/search/class-wp-rest-post-search-handler.php
@@ -71,7 +71,7 @@ class WP_REST_Post_Search_Handler extends WP_REST_Search_Handler {
 		}
 
 		/**
-		 * Filters the query arguments for a search request.
+		 * Filters the query arguments for a REST API search request.
 		 *
 		 * Enables adding extra arguments or setting defaults for a post search request.
 		 *
diff --git a/src/wp-includes/rest-api/search/class-wp-rest-term-search-handler.php b/src/wp-includes/rest-api/search/class-wp-rest-term-search-handler.php
index fb8180de90..90abe743c6 100644
--- a/src/wp-includes/rest-api/search/class-wp-rest-term-search-handler.php
+++ b/src/wp-includes/rest-api/search/class-wp-rest-term-search-handler.php
@@ -66,7 +66,7 @@ class WP_REST_Term_Search_Handler extends WP_REST_Search_Handler {
 		}
 
 		/**
-		 * Filters the query arguments for a search request.
+		 * Filters the query arguments for a REST API search request.
 		 *
 		 * Enables adding extra arguments or setting defaults for a term search request.
 		 *