WordPress.org
Get WordPress

Make WordPress Core

Ticket #38398: 38398.2.patch

File 38398.2.patch, 22.8 KB (added by Soean, 8 years ago)

Docs: Improve documentation for WP_REST_Users_Controller, WP_REST_Terms_Controller, WP_REST_Taxonomies_Controller, WP_REST_Settings_Controller.

  • src/wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Settings_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
    310/**
    411 * Manage a WordPress site's settings.
    512 */
    6 
    713class WP_REST_Settings_Controller extends WP_REST_Controller {
    814
    915        protected $rest_base = 'settings';
    … …  
    1016        protected $namespace = 'wp/v2';
    1117
    1218        /**
    13          * Register the routes for the objects of the controller.
     19         * Registers the routes for the objects of the controller.
     20         *
     21         * @since 4.7.0
    1422         */
    1523        public function register_routes() {
    1624                register_rest_route( $this->namespace, '/' . $this->rest_base, array(
    … …  
    3139        }
    3240
    3341        /**
    34          * Check if a given request has access to read and manage settings.
     42         * Checks if a given request has access to read and manage settings.
    3543         *
     44         * @since 4.7.0
     45         *
    3646         * @param  WP_REST_Request $request Full details about the request.
    3747         * @return boolean
    3848         */
    … …  
    4151        }
    4252
    4353        /**
    44          * Get the settings.
     54         * Gets the settings.
    4555         *
     56         * @since 4.7.0
     57         *
    4658         * @param WP_REST_Request $request Full details about the request.
    4759         * @return WP_Error|array
    4860         */
    … …  
    8193        }
    8294
    8395        /**
    84          * Prepare a value for output based off a schema array.
     96         * Prepares a value for output based off a schema array.
    8597         *
    86          * @param  mixed $value
    87          * @param  array $schema
     98         * @since 4.7.0
     99         *
     100         * @param  mixed $value  Value to prepare.
     101         * @param  array $schema Schema to match.
    88102         * @return mixed
    89103         */
    90104        protected function prepare_value( $value, $schema ) {
    … …  
    101115        }
    102116
    103117        /**
    104          * Update settings for the settings object.
     118         * Updates settings for the settings object.
    105119         *
     120         * @since 4.7.0
     121         *
    106122         * @param  WP_REST_Request $request Full detail about the request.
    107123         * @return WP_Error|array
    108124         */
    … …  
    147163        }
    148164
    149165        /**
    150          * Get all the registered options for the Settings API
     166         * Gets all the registered options for the Settings API.
    151167         *
     168         * @since 4.7.0
     169         *
    152170         * @return array
    153171         */
    154172        protected function get_registered_options() {
    … …  
    197215        }
    198216
    199217        /**
    200          * Get the site setting schema, conforming to JSON Schema.
     218         * Gets the site setting schema, conforming to JSON Schema.
    201219         *
     220         * @since 4.7.0
     221         *
    202222         * @return array
    203223         */
    204224        public function get_item_schema() {

  • src/wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Taxonomies_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
     10/**
     11 * Access taxonomies.
     12 *
     13 * @since 4.7.0
     14 */
    315class WP_REST_Taxonomies_Controller extends WP_REST_Controller {
    416
     17        /**
     18         * Constructor.
     19         *
     20         * @since 4.7.0
     21         */
    522        public function __construct() {
    623                $this->namespace = 'wp/v2';
    724                $this->rest_base = 'taxonomies';
    … …  
    825        }
    926
    1027        /**
    11          * Register the routes for the objects of the controller.
     28         * Registers the routes for the objects of the controller.
     29         *
     30         * @since 4.7.0
    1231         */
    1332        public function register_routes() {
    1433
    … …  
    3655        }
    3756
    3857        /**
    39          * Check whether a given request has permission to read taxonomies.
     58         * Checks whether a given request has permission to read taxonomies.
    4059         *
     60         * @since 4.7.0
     61         *
    4162         * @param  WP_REST_Request $request Full details about the request.
    4263         * @return WP_Error|boolean
    4364         */
    … …  
    5980        }
    6081
    6182        /**
    62          * Get all public taxonomies
     83         * Gets all public taxonomies.
    6384         *
    64          * @param WP_REST_Request $request
     85         * @since 4.7.0
     86         *
     87         * @param WP_REST_Request $request Full details about the request.
    6588         * @return array
    6689         */
    6790        public function get_items( $request ) {
    … …  
    93116        }
    94117
    95118        /**
    96          * Check if a given request has access a taxonomy
     119         * Checks if a given request has access a taxonomy.
    97120         *
     121         * @since 4.7.0
     122         *
    98123         * @param  WP_REST_Request $request Full details about the request.
    99124         * @return WP_Error|boolean
    100125         */
    … …  
    115140        }
    116141
    117142        /**
    118          * Get a specific taxonomy
     143         * Gets a specific taxonomy.
    119144         *
    120          * @param WP_REST_Request $request
     145         * @since 4.7.0
     146         *
     147         * @param WP_REST_Request $request Full details about the request.
    121148         * @return array|WP_Error
    122149         */
    123150        public function get_item( $request ) {
    … …  
    130157        }
    131158
    132159        /**
    133          * Prepare a taxonomy object for serialization
     160         * Prepares a taxonomy object for serialization.
    134161         *
    135          * @param stdClass $taxonomy Taxonomy data
    136          * @param WP_REST_Request $request
     162         * @since 4.7.0
     163         *
     164         * @param stdClass        $taxonomy Taxonomy data.
     165         * @param WP_REST_Request $request  Full details about the request.
    137166         * @return WP_REST_Response $response
    138167         */
    139168        public function prepare_item_for_response( $taxonomy, $request ) {
    … …  
    167196                ) );
    168197
    169198                /**
    170                  * Filter a taxonomy returned from the API.
     199                 * Filters a taxonomy returned from the API.
    171200                 *
    172201                 * Allows modification of the taxonomy data right before it is returned.
    173202                 *
     203                 * @since 4.7.0
     204                 *
    174205                 * @param WP_REST_Response  $response   The response object.
    175206                 * @param object            $item       The original taxonomy object.
    176207                 * @param WP_REST_Request   $request    Request used to generate the response.
    … …  
    179210        }
    180211
    181212        /**
    182          * Get the taxonomy's schema, conforming to JSON Schema
     213         * Gets the taxonomy's schema, conforming to JSON Schema.
    183214         *
     215         * @since 4.7.0
     216         *
    184217         * @return array
    185218         */
    186219        public function get_item_schema() {
    … …  
    243276        }
    244277
    245278        /**
    246          * Get the query params for collections
     279         * Gets the query params for collections.
    247280         *
     281         * @since 4.7.0
     282         *
    248283         * @return array
    249284         */
    250285        public function get_collection_params() {

  • src/wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Terms_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
    310/**
    411 * Access terms associated with a taxonomy.
     12 *
     13 * @since 4.7.0
    514 */
    615class WP_REST_Terms_Controller extends WP_REST_Controller {
    716
    … …  
    817        /**
    918         * Taxonomy key.
    1019         *
     20         * @since 4.7.0
    1121         * @access protected
    1222         * @var string
    1323         */
    … …  
    1626        /**
    1727         * Instance of a term meta fields object.
    1828         *
     29         * @since 4.7.0
    1930         * @access protected
    2031         * @var WP_REST_Term_Meta_Fields
    2132         */
    … …  
    2435        /**
    2536         * Column to have the terms be sorted by.
    2637         *
     38         * @since 4.7.0
    2739         * @access protected
    2840         * @var string
    2941         */
    … …  
    3244        /**
    3345         * Number of terms that were found.
    3446         *
     47         * @since 4.7.0
    3548         * @access protected
    3649         * @var int
    3750         */
    … …  
    4053        /**
    4154         * Constructor.
    4255         *
     56         * @since 4.7.0
     57         *
    4358         * @param string $taxonomy Taxonomy key.
    4459         */
    4560        public function __construct( $taxonomy ) {
    … …  
    5368
    5469        /**
    5570         * Registers the routes for the objects of the controller.
     71         *
     72         * @since 4.7.0
    5673         */
    5774        public function register_routes() {
    5875
    … …  
    104121        /**
    105122         * Checks if a request has access to read terms in the specified taxonomy.
    106123         *
     124         * @since 4.7.0
     125         *
    107126         * @param  WP_REST_Request $request Full details about the request.
    108127         * @return WP_Error|boolean
    109128         */
    … …  
    121140        /**
    122141         * Gets terms associated with a taxonomy.
    123142         *
     143         * @since 4.7.0
     144         *
    124145         * @param WP_REST_Request $request Full details about the request.
    125146         * @return WP_REST_Response|WP_Error
    126147         */
    … …  
    198219                        unset( $count_args['number'], $count_args['offset'] );
    199220                        $total_terms = wp_count_terms( $this->taxonomy, $count_args );
    200221
    201                         // wp_count_terms can return a falsy value when the term has no children
     222                        // wp_count_terms can return a falsy value when the term has no children.
    202223                        if ( ! $total_terms ) {
    203224                                $total_terms = 0;
    204225                        }
    … …  
    245266         * supported, notably `include`, `exclude`. In `self::get_items()` these
    246267         * are instead treated as a full query.
    247268         *
     269         * @since 4.7.0
     270         *
    248271         * @param array $prepared_args Arguments for get_terms().
    249272         * @return array List of term objects. (Total count in `$this->total_terms`)
    250273         */
    … …  
    286309        }
    287310
    288311        /**
    289          * Comparison function for sorting terms by a column.
     312         * Compares terms for sorting by a column.
    290313         *
    291314         * Uses `$this->sort_column` to determine field to sort by.
    292315         *
    293          * @access protected
     316         * @since 4.7.0
    294317         *
    295318         * @param stdClass $left Term object.
    296319         * @param stdClass $right Term object.
    … …  
    311334        /**
    312335         * Checks if a request has access to read the specified term.
    313336         *
     337         * @since 4.7.0
     338         *
    314339         * @param  WP_REST_Request $request Full details about the request.
    315340         * @return WP_Error|boolean
    316341         */
    … …  
    328353        /**
    329354         * Gets a single term from a taxonomy.
    330355         *
    331          * @param WP_REST_Request $request Full details about the request
     356         * @since 4.7.0
     357         *
     358         * @param WP_REST_Request $request Full details about the request.
    332359         * @return WP_REST_Request|WP_Error
    333360         */
    334361        public function get_item( $request ) {
    … …  
    349376        /**
    350377         * Checks if a request has access to create a term.
    351378         *
     379         * @since 4.7.0
     380         *
    352381         * @param  WP_REST_Request $request Full details about the request.
    353382         * @return WP_Error|boolean
    354383         */
    … …  
    369398        /**
    370399         * Creates a single term in a taxonomy.
    371400         *
    372          * @param WP_REST_Request $request Full details about the request
     401         * @since 4.7.0
     402         *
     403         * @param WP_REST_Request $request Full details about the request.
    373404         * @return WP_REST_Request|WP_Error
    374405         */
    375406        public function create_item( $request ) {
    … …  
    389420
    390421                $term = wp_insert_term( $prepared_term->name, $this->taxonomy, $prepared_term );
    391422                if ( is_wp_error( $term ) ) {
    392 
    393423                        /*
    394424                         * If we're going to inform the client that the term already exists,
    395425                         * give them the identifier for future use.
    … …  
    407437                /**
    408438                 * Fires after a single term is created or updated via the REST API.
    409439                 *
     440                 * @since 4.7.0
     441                 *
    410442                 * @param WP_Term         $term     Inserted Term object.
    411443                 * @param WP_REST_Request $request  Request object.
    412444                 * @param boolean         $creating True when creating term, false when updating.
    … …  
    437469        /**
    438470         * Checks if a request has access to update the specified term.
    439471         *
     472         * @since 4.7.0
     473         *
    440474         * @param  WP_REST_Request $request Full details about the request.
    441475         * @return WP_Error|boolean
    442476         */
    … …  
    462496        /**
    463497         * Updates a single term from a taxonomy.
    464498         *
    465          * @param WP_REST_Request $request Full details about the request
     499         * @since 4.7.0
     500         *
     501         * @param WP_REST_Request $request Full details about the request.
    466502         * @return WP_REST_Request|WP_Error
    467503         */
    468504        public function update_item( $request ) {
    … …  
    516552        /**
    517553         * Checks if a request has access to delete the specified term.
    518554         *
     555         * @since 4.7.0
     556         *
    519557         * @param  WP_REST_Request $request Full details about the request.
    520558         * @return WP_Error|boolean
    521559         */
    … …  
    537575        /**
    538576         * Deletes a single term from a taxonomy.
    539577         *
    540          * @param WP_REST_Request $request Full details about the request
     578         * @since 4.7.0
     579         *
     580         * @param WP_REST_Request $request Full details about the request.
    541581         * @return WP_REST_Response|WP_Error
    542582         */
    543583        public function delete_item( $request ) {
    … …  
    573613        /**
    574614         * Prepares a single term for create or update.
    575615         *
     616         * @since 4.7.0
     617         *
    576618         * @param WP_REST_Request $request Request object.
    577619         * @return object $prepared_term Term object.
    578620         */
    … …  
    610652                /**
    611653                 * Filters term data before inserting term via the REST API.
    612654                 *
     655                 * @since 4.7.0
     656                 *
    613657                 * @param object          $prepared_term Term object.
    614658                 * @param WP_REST_Request $request       Request object.
    615659                 */
    … …  
    619663        /**
    620664         * Prepares a single term output for response.
    621665         *
     666         * @since 4.7.0
     667         *
    622668         * @param obj             $item    Term object.
    623669         * @param WP_REST_Request $request Request object.
    624670         * @return WP_REST_Response $response
    … …  
    668714                 *
    669715                 * Allows modification of the term data right before it is returned.
    670716                 *
     717                 * @since 4.7.0
     718                 *
    671719                 * @param WP_REST_Response  $response  The response object.
    672720                 * @param object            $item      The original term object.
    673721                 * @param WP_REST_Request   $request   Request used to generate the response.
    … …  
    678726        /**
    679727         * Prepares links for the request.
    680728         *
     729         * @since 4.7.0
     730         *
    681731         * @param object $term Term object.
    682732         * @return array Links for the given term.
    683733         */
    … …  
    731781        /**
    732782         * Gets the term's schema, conforming to JSON Schema.
    733783         *
     784         * @since 4.7.0
     785         *
    734786         * @return array
    735787         */
    736788        public function get_item_schema() {
    … …  
    808860        /**
    809861         * Gets the query params for collections.
    810862         *
     863         * @since 4.7.0
     864         *
    811865         * @return array
    812866         */
    813867        public function get_collection_params() {
    … …  
    894948        /**
    895949         * Checks that the taxonomy is valid.
    896950         *
     951         * @since 4.7.0
     952         *
    897953         * @param string $taxonomy Taxonomy to check.
    898954         * @return WP_Error|boolean
    899955         */

  • src/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php

     
    11<?php
     2/**
     3 * REST API: WP_REST_Users_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
    29
    310/**
    4  * Access users
     11 * Access users.
     12 *
     13 * @since 4.7.0
    514 */
    615class WP_REST_Users_Controller extends WP_REST_Controller {
    716
    … …  
    817        /**
    918         * Instance of a user meta fields object.
    1019         *
     20         * @since 4.7.0
    1121         * @access protected
    1222         * @var WP_REST_User_Meta_Fields
    1323         */
    1424        protected $meta;
    1525
     26        /**
     27         * Constructor.
     28         *
     29         * @since 4.7.0
     30         */
    1631        public function __construct() {
    1732                $this->namespace = 'wp/v2';
    1833                $this->rest_base = 'users';
    … …  
    2136        }
    2237
    2338        /**
    24          * Register the routes for the objects of the controller.
     39         * Registers the routes for the objects of the controller.
     40         *
     41         * @since 4.7.0
    2542         */
    2643        public function register_routes() {
    2744
    … …  
    83100        /**
    84101         * Permissions check for getting all users.
    85102         *
     103         * @since 4.7.0
     104         *
    86105         * @param WP_REST_Request $request Full details about the request.
    87106         * @return WP_Error|boolean
    88107         */
    … …  
    104123        }
    105124
    106125        /**
    107          * Get all users
     126         * Gets all users.
    108127         *
     128         * @since 4.7.0
     129         *
    109130         * @param WP_REST_Request $request Full details about the request.
    110131         * @return WP_Error|WP_REST_Response
    111132         */
    … …  
    170191                }
    171192
    172193                /**
    173                  * Filter arguments, before passing to WP_User_Query, when querying users via the REST API.
     194                 * Filters arguments, before passing to WP_User_Query, when querying users via the REST API.
    174195                 *
     196                 * @since 4.7.0
     197                 *
    175198                 * @see https://developer.wordpress.org/reference/classes/wp_user_query/
    176199                 *
    177200                 * @param array           $prepared_args Array of arguments for WP_User_Query.
    … …  
    197220
    198221                $total_users = $query->get_total();
    199222                if ( $total_users < 1 ) {
    200                         // Out-of-bounds, run the query again without LIMIT for total count
     223                        // Out-of-bounds, run the query again without LIMIT for total count.
    201224                        unset( $prepared_args['number'], $prepared_args['offset'] );
    202225                        $count_query = new WP_User_Query( $prepared_args );
    203226                        $total_users = $count_query->get_total();
    … …  
    225248        }
    226249
    227250        /**
    228          * Check if a given request has access to read a user
     251         * Checks if a given request has access to read a user.
    229252         *
     253         * @since 4.7.0
     254         *
    230255         * @param  WP_REST_Request $request Full details about the request.
    231256         * @return WP_Error|boolean
    232257         */
    … …  
    254279        }
    255280
    256281        /**
    257          * Get a single user
     282         * Gets a single user.
    258283         *
     284         * @since 4.7.0
     285         *
    259286         * @param WP_REST_Request $request Full details about the request.
    260287         * @return WP_Error|WP_REST_Response
    261288         */
    … …  
    274301        }
    275302
    276303        /**
    277          * Get the current user
     304         * Gets the current user.
    278305         *
     306         * @since 4.7.0
     307         *
    279308         * @param WP_REST_Request $request Full details about the request.
    280309         * @return WP_Error|WP_REST_Response
    281310         */
    … …  
    295324        }
    296325
    297326        /**
    298          * Check if a given request has access create users
     327         * Checks if a given request has access create users.
    299328         *
     329         * @since 4.7.0
     330         *
    300331         * @param  WP_REST_Request $request Full details about the request.
    301332         * @return WP_Error|boolean
    302333         */
    … …  
    310341        }
    311342
    312343        /**
    313          * Create a single user
     344         * Creates a single user.
    314345         *
     346         * @since 4.7.0
     347         *
    315348         * @param WP_REST_Request $request Full details about the request.
    316349         * @return WP_Error|WP_REST_Response
    317350         */
    … …  
    375408                /**
    376409                 * Fires after a user is created or updated via the REST API.
    377410                 *
     411                 * @since 4.7.0
     412                 *
    378413                 * @param WP_User         $user      Data used to create the user.
    379414                 * @param WP_REST_Request $request   Request object.
    380415                 * @param boolean         $creating  True when creating user, false when updating user.
    … …  
    391426        }
    392427
    393428        /**
    394          * Check if a given request has access update a user
     429         * Checks if a given request has access update a user.
    395430         *
     431         * @since 4.7.0
     432         *
    396433         * @param  WP_REST_Request $request Full details about the request.
    397434         * @return WP_Error|boolean
    398435         */
    … …  
    412449        }
    413450
    414451        /**
    415          * Update a single user
     452         * Updates a single user.
    416453         *
     454         * @since 4.7.0
     455         *
    417456         * @param WP_REST_Request $request Full details about the request.
    418457         * @return WP_Error|WP_REST_Response
    419458         */
    … …  
    446485
    447486                $user = $this->prepare_item_for_database( $request );
    448487
    449                 // Ensure we're operating on the same user we already checked
     488                // Ensure we're operating on the same user we already checked.
    450489                $user->ID = $id;
    451490
    452491                $user_id = wp_update_user( $user );
    … …  
    482521        }
    483522
    484523        /**
    485          * Check if a given request has access delete a user
     524         * Checks if a given request has access delete a user.
    486525         *
     526         * @since 4.7.0
     527         *
    487528         * @param  WP_REST_Request $request Full details about the request.
    488529         * @return WP_Error|boolean
    489530         */
    … …  
    499540        }
    500541
    501542        /**
    502          * Delete a single user
     543         * Deletes a single user.
    503544         *
     545         * @since 4.7.0
     546         *
    504547         * @param WP_REST_Request $request Full details about the request.
    505548         * @return WP_Error|WP_REST_Response
    506549         */
    … …  
    509552                $reassign = isset( $request['reassign'] ) ? absint( $request['reassign'] ) : null;
    510553                $force = isset( $request['force'] ) ? (bool) $request['force'] : false;
    511554
    512                 // We don't support trashing for this type, error out
     555                // We don't support trashing for this type, error out.
    513556                if ( ! $force ) {
    514557                        return new WP_Error( 'rest_trash_not_supported', __( 'Users do not support trashing.' ), array( 'status' => 501 ) );
    515558                }
    … …  
    540583                /**
    541584                 * Fires after a user is deleted via the REST API.
    542585                 *
     586                 * @since 4.7.0
     587                 *
    543588                 * @param WP_User          $user     The user data.
    544589                 * @param WP_REST_Response $response The response returned from the API.
    545590                 * @param WP_REST_Request  $request  The request sent to the API.
    … …  
    550595        }
    551596
    552597        /**
    553          * Prepare a single user output for response
     598         * Prepares a single user output for response.
    554599         *
    555          * @param object $user User object.
     600         * @since 4.7.0
     601         *
     602         * @param object          $user    User object.
    556603         * @param WP_REST_Request $request Request object.
    557604         * @return WP_REST_Response $response Response data.
    558605         */
    … …  
    634681                $data = $this->add_additional_fields_to_object( $data, $request );
    635682                $data = $this->filter_response_by_context( $data, $context );
    636683
    637                 // Wrap the data in a response object
     684                // Wrap the data in a response object.
    638685                $response = rest_ensure_response( $data );
    639686
    640687                $response->add_links( $this->prepare_links( $user ) );
    641688
    642689                /**
    643                  * Filter user data returned from the REST API.
     690                 * Filters user data returned from the REST API.
    644691                 *
     692                 * @since 4.7.0
     693                 *
    645694                 * @param WP_REST_Response $response  The response object.
    646695                 * @param object           $user      User object used to create response.
    647696                 * @param WP_REST_Request  $request   Request object.
    … …  
    650699        }
    651700
    652701        /**
    653          * Prepare links for the request.
     702         * Prepares links for the request.
    654703         *
     704         * @since 4.7.0
     705         *
    655706         * @param WP_Post $user User object.
    656707         * @return array Links for the given user.
    657708         */
    … …  
    669720        }
    670721
    671722        /**
    672          * Prepare a single user for create or update
     723         * Prepares a single user for create or update.
    673724         *
     725         * @since 4.7.0
     726         *
    674727         * @param WP_REST_Request $request Request object.
    675728         * @return object $prepared_user User object.
    676729         */
    … …  
    723776                }
    724777
    725778                /**
    726                  * Filter user data before inserting user via the REST API.
     779                 * Filters user data before inserting user via the REST API.
    727780                 *
     781                 * @since 4.7.0
     782                 *
    728783                 * @param object          $prepared_user User object.
    729784                 * @param WP_REST_Request $request       Request object.
    730785                 */
    … …  
    732787        }
    733788
    734789        /**
    735          * Determine if the current user is allowed to make the desired roles change.
     790         * Determines if the current user is allowed to make the desired roles change.
    736791         *
     792         * @since 4.7.0
     793         *
    737794         * @param integer $user_id User ID.
    738795         * @param array   $roles   New user roles.
    739796         * @return WP_Error|boolean
    … …  
    754811                                return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => rest_authorization_required_code() ) );
    755812                        }
    756813
    757                         // The new role must be editable by the logged-in user.
    758 
    759814                        /** Include admin functions to get access to get_editable_roles() */
    760815                        require_once ABSPATH . 'wp-admin/includes/admin.php';
    761816
     817                        // The new role must be editable by the logged-in user.
    762818                        $editable_roles = get_editable_roles();
    763819                        if ( empty( $editable_roles[ $role ] ) ) {
    764820                                return new WP_Error( 'rest_user_invalid_role', __( 'You cannot give resource that role.' ), array( 'status' => 403 ) );
    … …  
    766822                }
    767823
    768824                return true;
    769 
    770825        }
    771826
    772827        /**
    773          * Get the User's schema, conforming to JSON Schema
     828         * Gets the User's schema, conforming to JSON Schema.
    774829         *
     830         * @since 4.7.0
     831         *
    775832         * @return array
    776833         */
    777834        public function get_item_schema() {
    … …  
    878935                                'password'        => array(
    879936                                        'description' => __( 'Password for the resource (never included).' ),
    880937                                        'type'        => 'string',
    881                                         'context'     => array(), // Password is never displayed
     938                                        'context'     => array(), // Password is never displayed.
    882939                                        'required'    => true,
    883940                                ),
    884941                                'capabilities'    => array(
    … …  
    924981        }
    925982
    926983        /**
    927          * Get the query params for collections
     984         * Gets the query params for collections.
    928985         *
     986         * @since 4.7.0
     987         *
    929988         * @return array
    930989         */
    931990        public function get_collection_params() {