Index: src/wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php =================================================================== --- src/wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php (revision 38853) +++ src/wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php (working copy) @@ -1,9 +1,15 @@ namespace, '/' . $this->rest_base, array( @@ -31,8 +39,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 +51,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 +93,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 +115,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 +163,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 +215,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: src/wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php =================================================================== --- src/wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php (revision 38853) +++ src/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: src/wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php =================================================================== --- src/wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php (revision 38853) +++ src/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: src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php =================================================================== --- src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php (revision 38853) +++ src/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() {