Index: wp-includes/rest-api/class-wp-rest-request.php =================================================================== --- wp-includes/rest-api/class-wp-rest-request.php (revision 38883) +++ wp-includes/rest-api/class-wp-rest-request.php (working copy) @@ -359,7 +359,7 @@ // Ensure we parse the body data. $body = $this->get_body(); - if ( $this->method !== 'POST' && ! empty( $body ) ) { + if ( 'POST' !== $this->method && ! empty( $body ) ) { $this->parse_body_params(); } @@ -967,7 +967,7 @@ $api_root = rest_url(); if ( get_option( 'permalink_structure' ) && 0 === strpos( $url, $api_root ) ) { - // Pretty permalinks on, and URL is under the API root + // Pretty permalinks on, and URL is under the API root. $api_url_part = substr( $url, strlen( untrailingslashit( $api_root ) ) ); $route = parse_url( $api_url_part, PHP_URL_PATH ); } elseif ( ! empty( $query_params['rest_route'] ) ) { Index: wp-includes/rest-api/class-wp-rest-response.php =================================================================== --- wp-includes/rest-api/class-wp-rest-response.php (revision 38883) +++ wp-includes/rest-api/class-wp-rest-response.php (working copy) @@ -246,7 +246,7 @@ $data = $this->get_data(); $error->add( $data['code'], $data['message'], $data['data'] ); if ( ! empty( $data['additional_errors'] ) ) { - foreach( $data['additional_errors'] as $err ) { + foreach ( $data['additional_errors'] as $err ) { $error->add( $err['code'], $err['message'], $err['data'] ); } } Index: wp-includes/rest-api/class-wp-rest-server.php =================================================================== --- wp-includes/rest-api/class-wp-rest-server.php (revision 38883) +++ wp-includes/rest-api/class-wp-rest-server.php (working copy) @@ -394,7 +394,7 @@ } if ( $jsonp_callback ) { - // Prepend '/**/' to mitigate possible JSONP Flash attacks + // Prepend '/**/' to mitigate possible JSONP Flash attacks. // https://miki.it/blog/2014/7/8/abusing-jsonp-with-rosetta-flash/ echo '/**/' . $jsonp_callback . '(' . $result . ')'; } else { @@ -505,7 +505,7 @@ continue; } - // Relation now changes from '$uri' to '$curie:$relation' + // Relation now changes from '$uri' to '$curie:$relation'. $rel_regex = str_replace( '\{rel\}', '(.+)', preg_quote( $curie['href'], '!' ) ); preg_match( '!' . $rel_regex . '!', $rel, $matches ); if ( $matches ) { @@ -588,7 +588,7 @@ if ( $has_links ) { $embedded[ $rel ] = $embeds; } - } + } // End foreach(). if ( ! empty( $embedded ) ) { $data['_embedded'] = $embedded; @@ -744,7 +744,7 @@ // Allow comma-separated HTTP methods. if ( is_string( $handler['methods'] ) ) { $methods = explode( ',', $handler['methods'] ); - } else if ( is_array( $handler['methods'] ) ) { + } elseif ( is_array( $handler['methods'] ) ) { $methods = $handler['methods']; } else { $methods = array(); @@ -756,8 +756,8 @@ $method = strtoupper( trim( $method ) ); $handler['methods'][ $method ] = true; } - } - } + } // End foreach(). + } // End foreach(). return $endpoints; } @@ -899,7 +899,7 @@ if ( is_wp_error( $permission ) ) { $response = $permission; - } else if ( false === $permission || null === $permission ) { + } elseif ( false === $permission || null === $permission ) { $response = new WP_Error( 'rest_forbidden', __( 'Sorry, you are not allowed to do that.' ), array( 'status' => 403 ) ); } } @@ -961,8 +961,8 @@ $response->set_matched_handler( $handler ); return $response; - } - } + } // End foreach(). + } // End foreach(). return $this->error_to_response( new WP_Error( 'rest_no_route', __( 'No route was found matching the URL and request method' ), array( 'status' => 404 ) ) ); } @@ -1196,7 +1196,7 @@ 'self' => rest_url( $route ), ); } - } + } // End foreach(). if ( empty( $data['methods'] ) ) { // No methods supported, hide the route. Index: wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php =================================================================== --- wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php (revision 38883) +++ wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php (working copy) @@ -1,5 +1,17 @@ 400 ) ); } - // Get the file via $_FILES or raw data + // Get the file via $_FILES or raw data. $files = $request->get_file_params(); $headers = $request->get_headers(); if ( ! empty( $files ) ) { @@ -146,6 +164,8 @@ /** * Fires after a single attachment is created or updated via the REST API. * + * @since 4.7.0 + * * @param object $attachment Inserted attachment. * @param WP_REST_Request $request The request sent to the API. * @param boolean $creating True when creating an attachment, false when updating. @@ -159,6 +179,8 @@ /** * Update a single post. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response Response object on success, WP_Error object on failure. */ @@ -198,6 +220,8 @@ /** * Prepare a single attachment for create or update. * + * @since 4.7.0 + * * @param WP_REST_Request $request Request object. * @return WP_Error|stdClass $prepared_attachment Post object. */ @@ -222,6 +246,8 @@ /** * Prepare a single attachment output for response. * + * @since 4.7.0 + * * @param WP_Post $post Post object. * @param WP_REST_Request $request Request object. * @return WP_REST_Response Response object. @@ -288,6 +314,8 @@ * * Allows modification of the attachment right before it is returned. * + * @since 4.7.0 + * * @param WP_REST_Response $response The response object. * @param WP_Post $post The original attachment post. * @param WP_REST_Request $request Request used to generate the response. @@ -298,6 +326,8 @@ /** * Get the Attachment's schema, conforming to JSON Schema. * + * @since 4.7.0 + * * @return array Item schema as an array. */ public function get_item_schema() { @@ -365,6 +395,8 @@ /** * Handle an upload via raw POST data. * + * @since 4.7.0 + * * @param array $data Supplied file data. * @param array $headers HTTP headers from the request. * @return array|WP_Error Data from {@see wp_handle_sideload()}. @@ -459,6 +491,8 @@ * | ext-token "=" ext-value * ext-token = * + * @since 4.7.0 + * * @see http://tools.ietf.org/html/rfc2388 * @see http://tools.ietf.org/html/rfc6266 * @@ -506,6 +540,8 @@ /** * Get the query params for collections of attachments. * + * @since 4.7.0 + * * @return array Query parameters for the attachment collection as an array. */ public function get_collection_params() { @@ -531,6 +567,8 @@ /** * Validate whether the user can query private statuses * + * @since 4.7.0 + * * @param mixed $value Status value. * @param WP_REST_Request $request Request object. * @param string $parameter Additional parameter to pass to validation. @@ -546,6 +584,8 @@ /** * Handle an upload via multipart/form-data ($_FILES). * + * @since 4.7.0 + * * @param array $files Data from $_FILES. * @param array $headers HTTP headers from the request. * @return array|WP_Error Data from {@see wp_handle_upload()}. @@ -590,6 +630,8 @@ * * Media types are considered the MIME type category. * + * @since 4.7.0 + * * @return array */ protected function get_media_types() { Index: wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php =================================================================== --- wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php (revision 38883) +++ wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php (working copy) @@ -1,7 +1,16 @@ namespace = 'wp/v2'; $this->rest_base = 'comments'; @@ -21,7 +36,9 @@ } /** - * Register the routes for the objects of the controller. + * Registers the routes for the objects of the controller. + * + * @since 4.7.0 */ public function register_routes() { @@ -72,8 +89,10 @@ } /** - * Check if a given request has access to read comments + * Checks if a given request has access to read comments. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -119,8 +138,10 @@ } /** - * Get a list of comments. + * Gets a list of comments. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -190,7 +211,7 @@ } /** - * Filter arguments, before passing to WP_Comment_Query, when querying comments via the REST API. + * Filters arguments, before passing to WP_Comment_Query, when querying comments via the REST API. * * @see https://developer.wordpress.org/reference/classes/wp_comment_query/ * @@ -215,7 +236,7 @@ $total_comments = (int) $query->found_comments; $max_pages = (int) $query->max_num_pages; if ( $total_comments < 1 ) { - // Out-of-bounds, run the query again without LIMIT for total count + // Out-of-bounds, run the query again without LIMIT for total count. unset( $prepared_args['number'], $prepared_args['offset'] ); $query = new WP_Comment_Query; $prepared_args['count'] = true; @@ -247,8 +268,10 @@ } /** - * Check if a given request has access to read the comment + * Checks if a given request has access to read the comment. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -279,8 +302,10 @@ } /** - * Get a comment. + * Gets a comment. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -306,8 +331,10 @@ } /** - * Check if a given request has access to create a comment + * Checks if a given request has access to create a comment. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -354,8 +381,10 @@ } /** - * Create a comment. + * Creates a comment. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -384,7 +413,7 @@ $prepared_comment['comment_date_gmt'] = current_time( 'mysql', true ); } - // Set author data if the user's logged in + // Set author data if the user's logged in. $missing_author = empty( $prepared_comment['user_id'] ) && empty( $prepared_comment['comment_author'] ) && empty( $prepared_comment['comment_author_email'] ) @@ -445,6 +474,8 @@ * * Allows modification of the comment right before it is inserted via `wp_insert_comment`. * + * @since 4.7.0 + * * @param array $prepared_comment The prepared comment data for `wp_insert_comment`. * @param WP_REST_Request $request Request used to insert the comment. */ @@ -484,6 +515,8 @@ /** * Fires after a comment is created or updated via the REST API. * + * @since 4.7.0 + * * @param array $comment Comment as it exists in the database. * @param WP_REST_Request $request The request sent to the API. * @param boolean $creating True when creating a comment, false when updating. @@ -494,8 +527,10 @@ } /** - * Check if a given request has access to update a comment + * Checks if a given request has access to update a comment. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -513,8 +548,10 @@ } /** - * Edit a comment + * Edits a comment. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -582,8 +619,10 @@ } /** - * Check if a given request has access to delete a comment + * Checks if a given request has access to delete a comment. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -600,8 +639,10 @@ } /** - * Delete a comment. + * Deletes a comment. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -630,7 +671,7 @@ if ( $force ) { $result = wp_delete_comment( $comment->comment_ID, true ); } else { - // If we don't support trashing for this type, error out + // If we don't support trashing for this type, error out. if ( ! $supports_trash ) { return new WP_Error( 'rest_trash_not_supported', __( 'The comment does not support trashing.' ), array( 'status' => 501 ) ); } @@ -649,6 +690,8 @@ /** * Fires after a comment is deleted via the REST API. * + * @since 4.7.0 + * * @param object $comment The deleted comment data. * @param WP_REST_Response $response The response returned from the API. * @param WP_REST_Request $request The request sent to the API. @@ -659,8 +702,10 @@ } /** - * Prepare a single comment output for response. + * Prepares a single comment output for response. * + * @since 4.7.0 + * * @param object $comment Comment object. * @param WP_REST_Request $request Request object. * @return WP_REST_Response $response @@ -702,16 +747,18 @@ $data = $this->add_additional_fields_to_object( $data, $request ); $data = $this->filter_response_by_context( $data, $context ); - // Wrap the data in a response object + // Wrap the data in a response object. $response = rest_ensure_response( $data ); $response->add_links( $this->prepare_links( $comment ) ); /** - * Filter a comment returned from the API. + * Filters a comment returned from the API. * * Allows modification of the comment right before it is returned. * + * @since 4.7.0 + * * @param WP_REST_Response $response The response object. * @param object $comment The original comment object. * @param WP_REST_Request $request Request used to generate the response. @@ -720,8 +767,10 @@ } /** - * Prepare links for the request. + * Prepares links for the request. * + * @since 4.7.0 + * * @param object $comment Comment object. * @return array Links for the given comment. */ @@ -778,9 +827,11 @@ } /** - * Prepend internal property prefix to query parameters to match our response fields. + * Prepends internal property prefix to query parameters to match our response fields. * - * @param string $query_param + * @since 4.7.0 + * + * @param string $query_param Query parameter. * @return string $normalized */ protected function normalize_query_param( $query_param ) { @@ -808,9 +859,11 @@ } /** - * Check comment_approved to set comment status for single comment output. + * Checks comment_approved to set comment status for single comment output. * - * @param string|int $comment_approved + * @since 4.7.0 + * + * @param string|int $comment_approved comment status. * @return string $status */ protected function prepare_status_response( $comment_approved ) { @@ -837,8 +890,10 @@ } /** - * Prepare a single comment to be inserted into the database. + * Prepares a single comment to be inserted into the database. * + * @since 4.7.0 + * * @param WP_REST_Request $request Request object. * @return array|WP_Error $prepared_comment */ @@ -928,8 +983,10 @@ } /** - * Get the Comment's schema, conforming to JSON Schema + * Gets the Comment's schema, conforming to JSON Schema. * + * @since 4.7.0 + * * @return array */ public function get_item_schema() { @@ -1091,8 +1148,10 @@ } /** - * Get the query params for collections + * Gets the query params for collections. * + * @since 4.7.0 + * * @return array */ public function get_collection_params() { @@ -1217,10 +1276,12 @@ } /** - * Set the comment_status of a given comment object when creating or updating a comment. + * Sets the comment_status of a given comment object when creating or updating a comment. * - * @param string|int $new_status - * @param object $comment + * @since 4.7.0 + * + * @param string|int $new_status New comment status. + * @param object $comment Comment data. * @return boolean $changed */ protected function handle_status_param( $new_status, $comment ) { @@ -1261,10 +1322,12 @@ } /** - * Check if we can read a post. + * Checks if we can read a post. * * Correctly handles posts with the inherit status. * + * @since 4.7.0 + * * @param WP_Post $post Post Object. * @return boolean Can we read it? */ @@ -1275,9 +1338,11 @@ } /** - * Check if we can read a comment. + * Checks if we can read a comment. * - * @param object $comment Comment object. + * @since 4.7.0 + * + * @param object $comment Comment object. * @return boolean Can we read it? */ protected function check_read_permission( $comment ) { @@ -1306,9 +1371,11 @@ } /** - * Check if we can edit or delete a comment. + * Checks if we can edit or delete a comment. * - * @param object $comment Comment object. + * @since 4.7.0 + * + * @param object $comment Comment object. * @return boolean Can we edit or delete it? */ protected function check_edit_permission( $comment ) { Index: wp-includes/rest-api/endpoints/class-wp-rest-controller.php =================================================================== --- wp-includes/rest-api/endpoints/class-wp-rest-controller.php (revision 38883) +++ wp-includes/rest-api/endpoints/class-wp-rest-controller.php (working copy) @@ -1,11 +1,24 @@ namespace = 'wp/v2'; $this->rest_base = 'statuses'; @@ -8,7 +25,9 @@ } /** - * Register the routes for the objects of the controller. + * Registers the routes for the objects of the controller. + * + * @since 4.7.0 */ public function register_routes() { @@ -36,8 +55,10 @@ } /** - * Check whether a given request has permission to read post statuses. + * Checks whether a given request has permission to read post statuses. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -55,9 +76,11 @@ } /** - * Get all post statuses, depending on user context + * Gets all post statuses, depending on user context. * - * @param WP_REST_Request $request + * @since 4.7.0 + * + * @param WP_REST_Request $request Full details about the request. * @return array|WP_Error */ public function get_items( $request ) { @@ -78,6 +101,8 @@ /** * Check if a given request has access to read a post status. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -94,9 +119,11 @@ } /** - * Check whether a given post status should be visible + * Checks whether a given post status should be visible. * - * @param object $status + * @since 4.7.0 + * + * @param object $status Post status. * @return boolean */ protected function check_read_permission( $status ) { @@ -115,9 +142,11 @@ } /** - * Get a specific post status + * Gets a specific post status. * - * @param WP_REST_Request $request + * @since 4.7.0 + * + * @param WP_REST_Request $request Full details about the request. * @return array|WP_Error */ public function get_item( $request ) { @@ -130,10 +159,12 @@ } /** - * Prepare a post status object for serialization + * Prepares a post status object for serialization. * - * @param stdClass $status Post status data - * @param WP_REST_Request $request + * @since 4.7.0 + * + * @param stdClass $status Post status data. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response Post status data */ public function prepare_item_for_response( $status, $request ) { @@ -161,10 +192,12 @@ } /** - * Filter a status returned from the API. + * Filters a status returned from the 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 WP_REST_Request $request Request used to generate the response. @@ -173,8 +206,10 @@ } /** - * Get the Post status' schema, conforming to JSON Schema + * Gets the Post status' schema, conforming to JSON Schema. * + * @since 4.7.0 + * * @return array */ public function get_item_schema() { @@ -231,8 +266,10 @@ } /** - * Get the query params for collections + * Gets the query params for collections. * + * @since 4.7.0 + * * @return array */ public function get_collection_params() { Index: wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php =================================================================== --- wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php (revision 38883) +++ wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php (working copy) @@ -1,7 +1,24 @@ namespace = 'wp/v2'; $this->rest_base = 'types'; @@ -8,7 +25,9 @@ } /** - * Register the routes for the objects of the controller. + * Registers the routes for the objects of the controller. + * + * @since 4.7.0 */ public function register_routes() { @@ -35,8 +54,10 @@ } /** - * Check whether a given request has permission to read types. + * Checks whether a given request has permission to read types. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -53,9 +74,11 @@ } /** - * Get all public post types + * Gets all public post types. * - * @param WP_REST_Request $request + * @since 4.7.0 + * + * @param WP_REST_Request $request Full details about the request. * @return array|WP_Error */ public function get_items( $request ) { @@ -71,9 +94,11 @@ } /** - * Get a specific post type + * Gets a specific post type. * - * @param WP_REST_Request $request + * @since 4.7.0 + * + * @param WP_REST_Request $request Full details about the request. * @return array|WP_Error */ public function get_item( $request ) { @@ -92,10 +117,12 @@ } /** - * Prepare a post type object for serialization + * Prepares a post type object for serialization. * - * @param stdClass $post_type Post type data - * @param WP_REST_Request $request + * @since 4.7.0 + * + * @param stdClass $post_type Post type data. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response $response */ public function prepare_item_for_response( $post_type, $request ) { @@ -125,10 +152,12 @@ ) ); /** - * Filter a post type returned from the API. + * Filters a post type returned from the API. * * Allows modification of the post type data right before it is returned. * + * @since 4.7.0 + * * @param WP_REST_Response $response The response object. * @param object $item The original post type object. * @param WP_REST_Request $request Request used to generate the response. @@ -137,8 +166,10 @@ } /** - * Get the Post type's schema, conforming to JSON Schema + * Gets the Post type's schema, conforming to JSON Schema. * + * @since 4.7.0 + * * @return array */ public function get_item_schema() { @@ -189,8 +220,10 @@ } /** - * Get the query params for collections + * Gets the query params for collections. * + * @since 4.7.0 + * * @return array */ public function get_collection_params() { Index: wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php =================================================================== --- wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php (revision 38883) +++ wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php (working copy) @@ -1,10 +1,23 @@ 'post_status', ); - // For each known parameter which is both registered and present in the request, - // set the parameter's value on the query $args. + /* + * For each known parameter which is both registered and present + * in the request, set the parameter's value on the query $args. + */ foreach ( $parameter_mappings as $api_param => $wp_param ) { if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) { $args[ $wp_param ] = $request[ $api_param ]; @@ -197,11 +220,13 @@ $args['post_type'] = $this->post_type; /** - * Filter the query arguments for a request. + * Filters the query arguments for a request. * * Enables adding extra arguments or setting defaults for a post * collection request. * + * @since 4.7.0 + * * @see https://developer.wordpress.org/reference/classes/wp_query/ * * @param array $args Key value array of query var to query value. @@ -300,8 +325,10 @@ } /** - * Check if a given request has access to read a post. + * Checks if a given request has access to read a post. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -333,11 +360,13 @@ } /** - * Can the user access password-protected content? + * Checks if the user can access password-protected content. * * This method determines whether we need to override the regular password * check in core with a filter. * + * @since 4.7.0 + * * @param WP_Post $post Post to check against. * @param WP_REST_Request $request Request data to check. * @return bool True if the user can access password-protected content, false otherwise. @@ -363,8 +392,10 @@ } /** - * Get a single post. + * Gets a single post. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -387,8 +418,10 @@ } /** - * Check if a given request has access to create a post. + * Checks if a given request has access to create a post. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -411,8 +444,10 @@ } /** - * Create a single post. + * Creates a single post. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -498,8 +533,10 @@ } /** - * Check if a given request has access to update a post. + * Checks if a given request has access to update a post. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -524,8 +561,10 @@ } /** - * Update a single post. + * Updates a single post. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -602,8 +641,10 @@ } /** - * Check if a given request has access to delete a post. + * Checks if a given request has access to delete a post. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return bool|WP_Error */ @@ -619,8 +660,10 @@ } /** - * Delete a single post. + * Deletes a single post. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error */ @@ -640,10 +683,12 @@ } /** - * Filter whether a post is trashable. + * Filters whether a post is trashable. * * Return false to disable trash support for the post. * + * @since 4.7.0 + * * @param boolean $supports_trash Whether the post type support trashing. * @param WP_Post $post The Post object being considered for trashing support. */ @@ -692,9 +737,11 @@ } /** - * Determine the allowed query_vars for a get_items() response and + * Determines the allowed query_vars for a get_items() response and * prepare for WP_Query. * + * @since 4.7.0 + * * @param array $prepared_args Prepared WP_Query arguments. * @param WP_REST_Request $request Full details about the request. * @return array $query_args @@ -706,10 +753,12 @@ foreach ( $valid_vars as $var => $index ) { if ( isset( $prepared_args[ $var ] ) ) { /** - * Filter the query_vars used in `get_items` for the constructed query. + * Filters the query_vars used in `get_items` for the constructed query. * * The dynamic portion of the hook name, $var, refers to the query_var key. * + * @since 4.7.0 + * * @param mixed $prepared_args[ $var ] The query_var value. */ $query_args[ $var ] = apply_filters( "rest_query_var-{$var}", $prepared_args[ $var ] ); @@ -728,8 +777,10 @@ } /** - * Get all the WP Query vars that are allowed for the API request. + * Gets all the WP Query vars that are allowed for the API request. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return array */ @@ -737,10 +788,12 @@ global $wp; /** - * Filter the publicly allowed query vars. + * Filters the publicly allowed query vars. * * Allows adjusting of the default query vars that are made public. * + * @since 4.7.0 + * * @param array Array of allowed WP_Query query vars. */ $valid_vars = apply_filters( 'query_vars', $wp->public_query_vars ); @@ -748,7 +801,7 @@ $post_type_obj = get_post_type_object( $this->post_type ); if ( current_user_can( $post_type_obj->cap->edit_posts ) ) { /** - * Filter the allowed 'private' query vars for authorized users. + * Filters the allowed 'private' query vars for authorized users. * * If the user has the `edit_posts` capability, we also allow use of * private query parameters, which are only undesirable on the @@ -757,6 +810,8 @@ * To disable anyway, use * `add_filter( 'rest_private_query_vars', '__return_empty_array' );` * + * @since 4.7.0 + * * @param array $private_query_vars Array of allowed query vars for authorized users. * } */ @@ -781,12 +836,14 @@ $valid_vars = array_merge( $valid_vars, $rest_valid ); /** - * Filter allowed query vars for the REST API. + * Filters allowed query vars for the REST API. * * This filter allows you to add or remove query vars from the final allowed * list for all requests, including unauthenticated ones. To alter the * vars for editors only, {@see rest_private_query_vars}. * + * @since 4.7.0 + * * @param array { * Array of allowed WP_Query query vars. * @@ -800,9 +857,11 @@ } /** - * Check the post_date_gmt or modified_gmt and prepare any post or + * Checks the post_date_gmt or modified_gmt and prepare any post or * modified date for single post output. * + * @since 4.7.0 + * * @param string $date_gmt GMT publication time. * @param string|null $date Optional, default is null. Local publication time. * @return string|null ISO8601/RFC3339 formatted datetime. @@ -823,8 +882,10 @@ } /** - * Prepare a single post for create or update. + * Prepares a single post for create or update. * + * @since 4.7.0 + * * @param WP_REST_Request $request Request object. * @return WP_Error|stdClass $prepared_post Post object. */ @@ -960,11 +1021,13 @@ $prepared_post->ping_status = $request['ping_status']; } /** - * Filter a post before it is inserted via the REST API. + * Filters a post before it is inserted via the REST API. * * The dynamic portion of the hook name, $this->post_type, refers to post_type of the post being * prepared for insertion. * + * @since 4.7.0 + * * @param stdClass $prepared_post An object representing a single post prepared * for inserting or updating the database. * @param WP_REST_Request $request Request object. @@ -974,8 +1037,10 @@ } /** - * Determine validity and normalize provided status param. + * Determines validity and normalize provided status param. * + * @since 4.7.0 + * * @param string $post_status Post status. * @param object $post_type Post type. * @return WP_Error|string $post_status @@ -1008,8 +1073,10 @@ } /** - * Determine the featured media based on a request param. + * Determines the featured media based on a request param. * + * @since 4.7.0 + * * @param int $featured_media Featured Media ID. * @param int $post_id Post ID. * @return bool|WP_Error @@ -1031,8 +1098,10 @@ } /** - * Set the template for a page. + * Sets the template for a page. * + * @since 4.7.0 + * * @param string $template Page template filename. * @param integer $post_id Post ID. */ @@ -1045,8 +1114,10 @@ } /** - * Update the post's terms from a REST request. + * Updates the post's terms from a REST request. * + * @since 4.7.0 + * * @param int $post_id The post ID to update the terms form. * @param WP_REST_Request $request The request object with post and terms data. * @return null|WP_Error WP_Error on an error assigning any of the terms. @@ -1068,8 +1139,10 @@ } /** - * Check if a given post type should be viewed or managed. + * Checks if a given post type should be viewed or managed. * + * @since 4.7.0 + * * @param object|string $post_type Post type name or object. * @return boolean Is post type allowed? */ @@ -1086,10 +1159,12 @@ } /** - * Check if we can read a post. + * Checks if we can read a post. * * Correctly handles posts with the inherit status. * + * @since 4.7.0 + * * @param object $post Post object. * @return boolean Can we read it? */ @@ -1125,8 +1200,10 @@ } /** - * Check if we can edit a post. + * Checks if we can edit a post. * + * @since 4.7.0 + * * @param object $post Post object. * @return boolean Can we edit it? */ @@ -1141,8 +1218,10 @@ } /** - * Check if we can create a post. + * Checks if we can create a post. * + * @since 4.7.0 + * * @param object $post Post object. * @return boolean Can we create it?. */ @@ -1157,8 +1236,10 @@ } /** - * Check if we can delete a post. + * Checks if we can delete a post. * + * @since 4.7.0 + * * @param object $post Post object. * @return boolean Can we delete it? */ @@ -1173,8 +1254,10 @@ } /** - * Prepare a single post output for response. + * Prepares a single post output for response. * + * @since 4.7.0 + * * @param WP_Post $post Post object. * @param WP_REST_Request $request Request object. * @return WP_REST_Response $data @@ -1343,11 +1426,13 @@ $response->add_links( $this->prepare_links( $post ) ); /** - * Filter the post data for a response. + * Filters the post data for a response. * * The dynamic portion of the hook name, $this->post_type, refers to post_type of the post being * prepared for the response. * + * @since 4.7.0 + * * @param WP_REST_Response $response The response object. * @param WP_Post $post Post object. * @param WP_REST_Request $request Request object. @@ -1356,7 +1441,7 @@ } /** - * Overwrite the default protected title format. + * Overwrites the default protected title format. * * By default WordPress will show password protected posts with a title of * "Protected: %s", as the REST API communicates the protected status of a post @@ -1369,8 +1454,10 @@ } /** - * Prepare links for the request. + * Prepares links for the request. * + * @since 4.7.0 + * * @param WP_Post $post Post object. * @return array Links for the given post. */ @@ -1466,7 +1553,7 @@ } /** - * Get the Post's schema, conforming to JSON Schema. + * Gets the Post's schema, conforming to JSON Schema. * * @return array */ @@ -1476,9 +1563,7 @@ '$schema' => 'http://json-schema.org/draft-04/schema#', 'title' => $this->post_type, 'type' => 'object', - /* - * Base properties for every Post. - */ + // Base properties for every Post. 'properties' => array( 'date' => array( 'description' => __( "The date the object was published, in the site's timezone." ), @@ -1795,7 +1880,7 @@ } /** - * Get the query params for collections of attachments. + * Gets the query params for collections of attachments. * * @return array */ @@ -1938,8 +2023,10 @@ } /** - * Validate whether the user can query private statuses. + * Validates whether the user can query private statuses. * + * @since 4.7.0 + * * @param mixed $value Post status. * @param WP_REST_Request $request Full details about the request. * @param string $parameter Index: wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php =================================================================== --- wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php (revision 38883) +++ wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php (working copy) @@ -1,11 +1,53 @@ parent_post_type = $parent_post_type; $this->parent_controller = new WP_REST_Posts_Controller( $parent_post_type ); @@ -16,9 +58,9 @@ } /** - * Register routes for revisions based on post types supporting revisions + * Registers routes for revisions based on post types supporting revisions. * - * @access public + * @since 4.7.0 */ public function register_routes() { @@ -52,9 +94,9 @@ } /** - * Check if a given request has access to get revisions + * Checks if a given request has access to get revisions. * - * @access public + * @since 4.7.0 * * @param WP_REST_Request $request Full data about the request. * @return WP_Error|boolean @@ -74,9 +116,9 @@ } /** - * Get a collection of revisions + * Gets a collection of revisions. * - * @access public + * @since 4.7.0 * * @param WP_REST_Request $request Full data about the request. * @return WP_Error|WP_REST_Response @@ -99,9 +141,9 @@ } /** - * Check if a given request has access to get a specific revision + * Checks if a given request has access to get a specific revision. * - * @access public + * @since 4.7.0 * * @param WP_REST_Request $request Full data about the request. * @return WP_Error|boolean @@ -111,9 +153,9 @@ } /** - * Get one revision from the collection + * Gets one revision from the collection. * - * @access public + * @since 4.7.0 * * @param WP_REST_Request $request Full data about the request. * @return WP_Error|array @@ -135,9 +177,9 @@ } /** - * Check if a given request has access to delete a revision + * Checks if a given request has access to delete a revision. * - * @access public + * @since 4.7.0 * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean @@ -158,9 +200,9 @@ } /** - * Delete a single revision + * Deletes a single revision. * - * @access public + * @since 4.7.0 * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean @@ -171,6 +213,8 @@ /** * Fires after a revision is deleted via the REST API. * + * @since 4.7.0 + * * @param (mixed) $result The revision object (if it was deleted or moved to the trash successfully) * or false (failure). If the revision was moved to to the trash, $result represents * its new state; if it was deleted, $result represents its state before deletion. @@ -186,9 +230,9 @@ } /** - * Prepare the revision for the REST response + * Prepares the revision for the REST response. * - * @access public + * @since 4.7.0 * * @param WP_Post $post Post revision object. * @param WP_REST_Request $request Request object. @@ -273,7 +317,7 @@ } /** - * Filter a revision returned from the API. + * Filters a revision returned from the API. * * Allows modification of the revision right before it is returned. * @@ -285,7 +329,7 @@ } /** - * Check the post_date_gmt or modified_gmt and prepare any post or + * Checks the post_date_gmt or modified_gmt and prepare any post or * modified date for single post output. * * @access protected @@ -307,9 +351,9 @@ } /** - * Get the revision's schema, conforming to JSON Schema + * Gets the revision's schema, conforming to JSON Schema. * - * @access public + * @since 4.7.0 * * @return array */ @@ -318,9 +362,7 @@ '$schema' => 'http://json-schema.org/draft-04/schema#', 'title' => "{$this->parent_post_type}-revision", 'type' => 'object', - /* - * Base properties for every Revision - */ + // Base properties for every Revision. 'properties' => array( 'author' => array( 'description' => __( 'The id for the author of the object.' ), @@ -393,9 +435,9 @@ } /** - * Get the query params for collections + * Gets the query params for collections. * - * @access public + * @since 4.7.0 * * @return array */ @@ -406,7 +448,7 @@ } /** - * Check the post excerpt and prepare it for single post output. + * Checks the post excerpt and prepare it for single post output. * * @access protected * Index: wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php =================================================================== --- wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php (revision 38883) +++ wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php (working copy) @@ -1,9 +1,17 @@ namespace, '/' . $this->rest_base, array( @@ -31,8 +41,10 @@ } /** - * Check if a given request has access to read and manage settings. + * Checks if a given request has access to read and manage settings. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return boolean */ @@ -41,8 +53,10 @@ } /** - * Get the settings. + * Gets the settings. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|array */ @@ -81,10 +95,12 @@ } /** - * Prepare a value for output based off a schema array. + * Prepares a value for output based off a schema array. * - * @param mixed $value - * @param array $schema + * @since 4.7.0 + * + * @param mixed $value Value to prepare. + * @param array $schema Schema to match. * @return mixed */ protected function prepare_value( $value, $schema ) { @@ -101,8 +117,10 @@ } /** - * Update settings for the settings object. + * Updates settings for the settings object. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full detail about the request. * @return WP_Error|array */ @@ -147,8 +165,10 @@ } /** - * Get all the registered options for the Settings API + * Gets all the registered options for the Settings API. * + * @since 4.7.0 + * * @return array */ protected function get_registered_options() { @@ -197,8 +217,10 @@ } /** - * Get the site setting schema, conforming to JSON Schema. + * Gets the site setting schema, conforming to JSON Schema. * + * @since 4.7.0 + * * @return array */ public function get_item_schema() { Index: wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php =================================================================== --- wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php (revision 38883) +++ wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php (working copy) @@ -1,7 +1,24 @@ namespace = 'wp/v2'; $this->rest_base = 'taxonomies'; @@ -8,7 +25,9 @@ } /** - * Register the routes for the objects of the controller. + * Registers the routes for the objects of the controller. + * + * @since 4.7.0 */ public function register_routes() { @@ -36,8 +55,10 @@ } /** - * Check whether a given request has permission to read taxonomies. + * Checks whether a given request has permission to read taxonomies. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -59,9 +80,11 @@ } /** - * Get all public taxonomies + * Gets all public taxonomies. * - * @param WP_REST_Request $request + * @since 4.7.0 + * + * @param WP_REST_Request $request Full details about the request. * @return array */ public function get_items( $request ) { @@ -93,8 +116,10 @@ } /** - * Check if a given request has access a taxonomy + * Checks if a given request has access a taxonomy. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -115,9 +140,11 @@ } /** - * Get a specific taxonomy + * Gets a specific taxonomy. * - * @param WP_REST_Request $request + * @since 4.7.0 + * + * @param WP_REST_Request $request Full details about the request. * @return array|WP_Error */ public function get_item( $request ) { @@ -130,10 +157,12 @@ } /** - * Prepare a taxonomy object for serialization + * Prepares a taxonomy object for serialization. * - * @param stdClass $taxonomy Taxonomy data - * @param WP_REST_Request $request + * @since 4.7.0 + * + * @param stdClass $taxonomy Taxonomy data. + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response $response */ public function prepare_item_for_response( $taxonomy, $request ) { @@ -167,10 +196,12 @@ ) ); /** - * Filter a taxonomy returned from the API. + * Filters a taxonomy returned from the API. * * Allows modification of the taxonomy data right before it is returned. * + * @since 4.7.0 + * * @param WP_REST_Response $response The response object. * @param object $item The original taxonomy object. * @param WP_REST_Request $request Request used to generate the response. @@ -179,8 +210,10 @@ } /** - * Get the taxonomy's schema, conforming to JSON Schema + * Gets the taxonomy's schema, conforming to JSON Schema. * + * @since 4.7.0 + * * @return array */ public function get_item_schema() { @@ -243,8 +276,10 @@ } /** - * Get the query params for collections + * Gets the query params for collections. * + * @since 4.7.0 + * * @return array */ public function get_collection_params() { Index: wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php =================================================================== --- wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php (revision 38883) +++ wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php (working copy) @@ -1,7 +1,16 @@ taxonomy, $count_args ); - // wp_count_terms can return a falsy value when the term has no children + // wp_count_terms can return a falsy value when the term has no children. if ( ! $total_terms ) { $total_terms = 0; } @@ -245,6 +266,8 @@ * supported, notably `include`, `exclude`. In `self::get_items()` these * are instead treated as a full query. * + * @since 4.7.0 + * * @param array $prepared_args Arguments for get_terms(). * @return array List of term objects. (Total count in `$this->total_terms`) */ @@ -286,11 +309,11 @@ } /** - * Comparison function for sorting terms by a column. + * Compares terms for sorting by a column. * * Uses `$this->sort_column` to determine field to sort by. * - * @access protected + * @since 4.7.0 * * @param stdClass $left Term object. * @param stdClass $right Term object. @@ -311,6 +334,8 @@ /** * Checks if a request has access to read the specified term. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -328,7 +353,9 @@ /** * Gets a single term from a taxonomy. * - * @param WP_REST_Request $request Full details about the request + * @since 4.7.0 + * + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Request|WP_Error */ public function get_item( $request ) { @@ -349,6 +376,8 @@ /** * Checks if a request has access to create a term. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -369,7 +398,9 @@ /** * Creates a single term in a taxonomy. * - * @param WP_REST_Request $request Full details about the request + * @since 4.7.0 + * + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Request|WP_Error */ public function create_item( $request ) { @@ -389,7 +420,6 @@ $term = wp_insert_term( $prepared_term->name, $this->taxonomy, $prepared_term ); if ( is_wp_error( $term ) ) { - /* * If we're going to inform the client that the term already exists, * give them the identifier for future use. @@ -407,6 +437,8 @@ /** * Fires after a single term is created or updated via the REST API. * + * @since 4.7.0 + * * @param WP_Term $term Inserted Term object. * @param WP_REST_Request $request Request object. * @param boolean $creating True when creating term, false when updating. @@ -437,6 +469,8 @@ /** * Checks if a request has access to update the specified term. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -462,7 +496,9 @@ /** * Updates a single term from a taxonomy. * - * @param WP_REST_Request $request Full details about the request + * @since 4.7.0 + * + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Request|WP_Error */ public function update_item( $request ) { @@ -516,6 +552,8 @@ /** * Checks if a request has access to delete the specified term. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -537,7 +575,9 @@ /** * Deletes a single term from a taxonomy. * - * @param WP_REST_Request $request Full details about the request + * @since 4.7.0 + * + * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error */ public function delete_item( $request ) { @@ -573,6 +613,8 @@ /** * Prepares a single term for create or update. * + * @since 4.7.0 + * * @param WP_REST_Request $request Request object. * @return object $prepared_term Term object. */ @@ -610,6 +652,8 @@ /** * Filters term data before inserting term via the REST API. * + * @since 4.7.0 + * * @param object $prepared_term Term object. * @param WP_REST_Request $request Request object. */ @@ -619,6 +663,8 @@ /** * Prepares a single term output for response. * + * @since 4.7.0 + * * @param obj $item Term object. * @param WP_REST_Request $request Request object. * @return WP_REST_Response $response @@ -668,6 +714,8 @@ * * Allows modification of the term data right before it is returned. * + * @since 4.7.0 + * * @param WP_REST_Response $response The response object. * @param object $item The original term object. * @param WP_REST_Request $request Request used to generate the response. @@ -678,6 +726,8 @@ /** * Prepares links for the request. * + * @since 4.7.0 + * * @param object $term Term object. * @return array Links for the given term. */ @@ -731,6 +781,8 @@ /** * Gets the term's schema, conforming to JSON Schema. * + * @since 4.7.0 + * * @return array */ public function get_item_schema() { @@ -808,6 +860,8 @@ /** * Gets the query params for collections. * + * @since 4.7.0 + * * @return array */ public function get_collection_params() { @@ -894,6 +948,8 @@ /** * Checks that the taxonomy is valid. * + * @since 4.7.0 + * * @param string $taxonomy Taxonomy to check. * @return WP_Error|boolean */ Index: wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php =================================================================== --- wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php (revision 38883) +++ wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php (working copy) @@ -1,7 +1,16 @@ namespace = 'wp/v2'; $this->rest_base = 'users'; @@ -21,7 +36,9 @@ } /** - * Register the routes for the objects of the controller. + * Registers the routes for the objects of the controller. + * + * @since 4.7.0 */ public function register_routes() { @@ -83,6 +100,8 @@ /** * Permissions check for getting all users. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -104,8 +123,10 @@ } /** - * Get all users + * Gets all users. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -170,8 +191,10 @@ } /** - * Filter arguments, before passing to WP_User_Query, when querying users via the REST API. + * Filters arguments, before passing to WP_User_Query, when querying users via the REST API. * + * @since 4.7.0 + * * @see https://developer.wordpress.org/reference/classes/wp_user_query/ * * @param array $prepared_args Array of arguments for WP_User_Query. @@ -197,7 +220,7 @@ $total_users = $query->get_total(); if ( $total_users < 1 ) { - // Out-of-bounds, run the query again without LIMIT for total count + // Out-of-bounds, run the query again without LIMIT for total count. unset( $prepared_args['number'], $prepared_args['offset'] ); $count_query = new WP_User_Query( $prepared_args ); $total_users = $count_query->get_total(); @@ -225,8 +248,10 @@ } /** - * Check if a given request has access to read a user + * Checks if a given request has access to read a user. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -254,8 +279,10 @@ } /** - * Get a single user + * Gets a single user. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -274,8 +301,10 @@ } /** - * Get the current user + * Gets the current user. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -295,8 +324,10 @@ } /** - * Check if a given request has access create users + * Checks if a given request has access create users. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -310,8 +341,10 @@ } /** - * Create a single user + * Creates a single user. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -375,6 +408,8 @@ /** * Fires after a user is created or updated via the REST API. * + * @since 4.7.0 + * * @param WP_User $user Data used to create the user. * @param WP_REST_Request $request Request object. * @param boolean $creating True when creating user, false when updating user. @@ -391,8 +426,10 @@ } /** - * Check if a given request has access update a user + * Checks if a given request has access update a user. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -412,8 +449,10 @@ } /** - * Update a single user + * Updates a single user. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -446,7 +485,7 @@ $user = $this->prepare_item_for_database( $request ); - // Ensure we're operating on the same user we already checked + // Ensure we're operating on the same user we already checked. $user->ID = $id; $user_id = wp_update_user( $user ); @@ -482,8 +521,10 @@ } /** - * Check if a given request has access delete a user + * Checks if a given request has access delete a user. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|boolean */ @@ -499,8 +540,10 @@ } /** - * Delete a single user + * Deletes a single user. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @return WP_Error|WP_REST_Response */ @@ -509,7 +552,7 @@ $reassign = isset( $request['reassign'] ) ? absint( $request['reassign'] ) : null; $force = isset( $request['force'] ) ? (bool) $request['force'] : false; - // We don't support trashing for this type, error out + // We don't support trashing for this type, error out. if ( ! $force ) { return new WP_Error( 'rest_trash_not_supported', __( 'Users do not support trashing.' ), array( 'status' => 501 ) ); } @@ -540,6 +583,8 @@ /** * Fires after a user is deleted via the REST API. * + * @since 4.7.0 + * * @param WP_User $user The user data. * @param WP_REST_Response $response The response returned from the API. * @param WP_REST_Request $request The request sent to the API. @@ -550,9 +595,11 @@ } /** - * Prepare a single user output for response + * Prepares a single user output for response. * - * @param object $user User object. + * @since 4.7.0 + * + * @param object $user User object. * @param WP_REST_Request $request Request object. * @return WP_REST_Response $response Response data. */ @@ -634,14 +681,16 @@ $data = $this->add_additional_fields_to_object( $data, $request ); $data = $this->filter_response_by_context( $data, $context ); - // Wrap the data in a response object + // Wrap the data in a response object. $response = rest_ensure_response( $data ); $response->add_links( $this->prepare_links( $user ) ); /** - * Filter user data returned from the REST API. + * Filters user data returned from the REST API. * + * @since 4.7.0 + * * @param WP_REST_Response $response The response object. * @param object $user User object used to create response. * @param WP_REST_Request $request Request object. @@ -650,8 +699,10 @@ } /** - * Prepare links for the request. + * Prepares links for the request. * + * @since 4.7.0 + * * @param WP_Post $user User object. * @return array Links for the given user. */ @@ -669,8 +720,10 @@ } /** - * Prepare a single user for create or update + * Prepares a single user for create or update. * + * @since 4.7.0 + * * @param WP_REST_Request $request Request object. * @return object $prepared_user User object. */ @@ -723,8 +776,10 @@ } /** - * Filter user data before inserting user via the REST API. + * Filters user data before inserting user via the REST API. * + * @since 4.7.0 + * * @param object $prepared_user User object. * @param WP_REST_Request $request Request object. */ @@ -732,8 +787,10 @@ } /** - * Determine if the current user is allowed to make the desired roles change. + * Determines if the current user is allowed to make the desired roles change. * + * @since 4.7.0 + * * @param integer $user_id User ID. * @param array $roles New user roles. * @return WP_Error|boolean @@ -754,11 +811,10 @@ return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => rest_authorization_required_code() ) ); } - // The new role must be editable by the logged-in user. - /** Include admin functions to get access to get_editable_roles() */ require_once ABSPATH . 'wp-admin/includes/admin.php'; + // The new role must be editable by the logged-in user. $editable_roles = get_editable_roles(); if ( empty( $editable_roles[ $role ] ) ) { return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => 403 ) ); @@ -766,12 +822,13 @@ } return true; - } /** - * Get the User's schema, conforming to JSON Schema + * Gets the User's schema, conforming to JSON Schema. * + * @since 4.7.0 + * * @return array */ public function get_item_schema() { @@ -878,7 +935,7 @@ 'password' => array( 'description' => __( 'Password for the resource (never included).' ), 'type' => 'string', - 'context' => array(), // Password is never displayed + 'context' => array(), // Password is never displayed. 'required' => true, ), 'capabilities' => array( @@ -924,8 +981,10 @@ } /** - * Get the query params for collections + * Gets the query params for collections. * + * @since 4.7.0 + * * @return array */ public function get_collection_params() { Index: wp-includes/rest-api/fields/class-wp-rest-comment-meta-fields.php =================================================================== --- wp-includes/rest-api/fields/class-wp-rest-comment-meta-fields.php (revision 38883) +++ wp-includes/rest-api/fields/class-wp-rest-comment-meta-fields.php (working copy) @@ -1,9 +1,24 @@ get_rest_field_type(), 'meta', array( @@ -34,6 +49,8 @@ /** * Get the `meta` field value. * + * @since 4.7.0 + * * @param int $object_id Object ID to fetch meta for. * @param WP_REST_Request $request Full details about the request. * @return WP_Error|object @@ -71,6 +88,8 @@ * the database, such as booleans. We need to cast back to the relevant * type before passing back to JSON. * + * @since 4.7.0 + * * @param mixed $value Value to prepare. * @param WP_REST_Request $request Current request object. * @param array $args Options for the field. @@ -87,6 +106,8 @@ /** * Update meta values. * + * @since 4.7.0 + * * @param WP_REST_Request $request Full details about the request. * @param int $object_id Object ID to fetch meta for. * @return WP_Error|null Error if one occurs, null on success. @@ -120,6 +141,8 @@ /** * Delete meta value for an object. * + * @since 4.7.0 + * * @param int $object_id Object ID the field belongs to. * @param string $name Key for the field. * @return bool|WP_Error True if meta field is deleted, error otherwise. @@ -149,6 +172,8 @@ * * Alters the list of values in the database to match the list of provided values. * + * @since 4.7.0 + * * @param int $object_id Object ID to update. * @param string $name Key for the custom field. * @param array $values List of values to update to. @@ -211,6 +236,8 @@ /** * Update meta value for an object. * + * @since 4.7.0 + * * @param int $object_id Object ID to update. * @param string $name Key for the custom field. * @param mixed $value Updated value. @@ -251,6 +278,8 @@ /** * Get all the registered meta fields. * + * @since 4.7.0 + * * @return array */ protected function get_registered_fields() { @@ -305,6 +334,8 @@ /** * Get the object's `meta` schema, conforming to JSON Schema. * + * @since 4.7.0 + * * @return array */ public function get_field_schema() { @@ -330,6 +361,8 @@ * Default preparation for meta fields. Override by passing the * `prepare_callback` in your `show_in_rest` options. * + * @since 4.7.0 + * * @param mixed $value Meta value from the database. * @param WP_REST_Request $request Request object. * @param array $args REST-specific options for the meta key. Index: wp-includes/rest-api/fields/class-wp-rest-post-meta-fields.php =================================================================== --- wp-includes/rest-api/fields/class-wp-rest-post-meta-fields.php (revision 38883) +++ wp-includes/rest-api/fields/class-wp-rest-post-meta-fields.php (working copy) @@ -1,9 +1,24 @@