Make WordPress Core

Changeset 59009


Ignore:
Timestamp:
09/11/2024 12:06:15 PM (2 years ago)
Author:
johnbillion
Message:

Docs: Various docblock improvements and corrections.

See #61608

Location:
trunk/src
Files:
12 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/translation-install.php

    r58813 r59009  
    1515 * @param string       $type Type of translations. Accepts 'plugins', 'themes', 'core'.
    1616 * @param array|object $args Translation API arguments. Optional.
    17  * @return array|WP_Error On success an associative array of translations, WP_Error on failure.
     17 * @return array|WP_Error {
     18 *     On success an associative array of translations, WP_Error on failure.
     19 *
     20 *     @type array $translations {
     21 *         List of translations, each an array of data.
     22 *
     23 *         @type array ...$0 {
     24 *             @type string   $language     Language code.
     25 *             @type string   $version      WordPress version.
     26 *             @type string   $updated      Date the translation was last updated, in MySQL datetime format.
     27 *             @type string   $english_name English name of the language.
     28 *             @type string   $native_name  Native name of the language.
     29 *             @type string   $package      URL to download the translation package.
     30 *             @type string[] $iso          Array of ISO language codes.
     31 *             @type array    $strings      Array of translated strings used in the installation process.
     32 *         }
     33 *     }
     34 * }
    1835 */
    1936function translations_api( $type, $args = null ) {
     
    101118         * @since 4.0.0
    102119         *
    103          * @param array|WP_Error $res  Response as an associative array or WP_Error.
     120         * @param array|WP_Error $res  {
     121         *     On success an associative array of translations, WP_Error on failure.
     122         *
     123         *     @type array $translations {
     124         *         List of translations, each an array of data.
     125         *
     126         *         @type array ...$0 {
     127         *             @type string   $language     Language code.
     128         *             @type string   $version      WordPress version.
     129         *             @type string   $updated      Date the translation was last updated, in MySQL datetime format.
     130         *             @type string   $english_name English name of the language.
     131         *             @type string   $native_name  Native name of the language.
     132         *             @type string   $package      URL to download the translation package.
     133         *             @type string[] $iso          Array of ISO language codes.
     134         *             @type array    $strings      Array of translated strings used in the installation process.
     135         *         }
     136         *     }
     137         * }
    104138         * @param string         $type The type of translations being requested.
    105139         * @param object         $args Translation API arguments.
     
    115149 * @see translations_api()
    116150 *
    117  * @return array[] Array of translations, each an array of data, keyed by the language. If the API response results
    118  *                 in an error, an empty array will be returned.
     151 * @return array {
     152 *     Array of translations keyed by the language code, each an associative array of data.
     153 *     If the API response results in an error, an empty array will be returned.
     154 *
     155 *     @type array ...$0 {
     156 *         @type string   $language     Language code.
     157 *         @type string   $version      WordPress version.
     158 *         @type string   $updated      Date the translation was last updated, in MySQL datetime format.
     159 *         @type string   $english_name English name of the language.
     160 *         @type string   $native_name  Native name of the language.
     161 *         @type string   $package      URL to download the translation package.
     162 *         @type string[] $iso          Array of ISO language codes.
     163 *         @type array    $strings      Array of translated strings used in the installation process.
     164 *     }
     165 * }
    119166 */
    120167function wp_get_available_translations() {
     
    133180
    134181        $translations = array();
    135         // Key the array with the language code for now.
     182        // Key the array with the language code.
    136183        foreach ( $api['translations'] as $translation ) {
    137184                $translations[ $translation['language'] ] = $translation;
  • trunk/src/wp-includes/blocks.php

    r58801 r59009  
    14331433 *
    14341434 * @param array $block {
    1435  *     A representative array of a single parsed block object. See WP_Block_Parser_Block.
     1435 *     An associative array of a single parsed block object. See WP_Block_Parser_Block.
    14361436 *
    14371437 *     @type string   $blockName    Name of block.
     
    14741474 *
    14751475 *     @type array ...$0 {
    1476  *         A representative array of a single parsed block object. See WP_Block_Parser_Block.
     1476 *         An associative array of a single parsed block object. See WP_Block_Parser_Block.
    14771477 *
    14781478 *         @type string   $blockName    Name of block.
     
    15161516 * @see serialize_block()
    15171517 *
    1518  * @param array    $block         A representative array of a single parsed block object. See WP_Block_Parser_Block.
     1518 * @param array    $block         An associative array of a single parsed block object. See WP_Block_Parser_Block.
    15191519 * @param callable $pre_callback  Callback to run on each block in the tree before it is traversed and serialized.
    15201520 *                                It is called with the following arguments: &$block, $parent_block, $previous_block.
     
    19981998 *
    19991999 * @param array $parsed_block {
    2000  *     A representative array of the block being rendered. See WP_Block_Parser_Block.
     2000 *     An associative array of the block being rendered. See WP_Block_Parser_Block.
    20012001 *
    20022002 *     @type string   $blockName    Name of block.
     
    20222022         * @param string|null   $pre_render   The pre-rendered content. Default null.
    20232023         * @param array         $parsed_block {
    2024          *     A representative array of the block being rendered. See WP_Block_Parser_Block.
     2024         *     An associative array of the block being rendered. See WP_Block_Parser_Block.
    20252025         *
    20262026         *     @type string   $blockName    Name of block.
     
    20482048         *
    20492049         * @param array         $parsed_block {
    2050          *     A representative array of the block being rendered. See WP_Block_Parser_Block.
     2050         *     An associative array of the block being rendered. See WP_Block_Parser_Block.
    20512051         *
    20522052         *     @type string   $blockName    Name of block.
     
    20962096         * @param array         $context      Default context.
    20972097         * @param array         $parsed_block {
    2098          *     A representative array of the block being rendered. See WP_Block_Parser_Block.
     2098         *     An associative array of the block being rendered. See WP_Block_Parser_Block.
    20992099         *
    21002100         *     @type string   $blockName    Name of block.
     
    21252125 *
    21262126 *     @type array ...$0 {
    2127  *         A representative array of a single parsed block object. See WP_Block_Parser_Block.
     2127 *         An associative array of a single parsed block object. See WP_Block_Parser_Block.
    21282128 *
    21292129 *         @type string   $blockName    Name of block.
  • trunk/src/wp-includes/class-wp-application-passwords.php

    r55732 r59009  
    7272         *     Application password details, or a WP_Error instance if an error occurs.
    7373         *
    74          *     @type string $0 The unhashed generated application password.
     74         *     @type string $0 The generated application password in plain text.
    7575         *     @type array  $1 {
    7676         *         The details about the created password.
     
    142142                 *     @type null   $last_ip   Null.
    143143                 * }
    144                  * @param string $new_password The unhashed generated application password.
     144                 * @param string $new_password The generated application password in plain text.
    145145                 * @param array  $args         {
    146146                 *     Arguments used to create the application password.
     
    162162         * @param int $user_id User ID.
    163163         * @return array {
    164          *     The list of app passwords.
     164         *     The list of application passwords.
    165165         *
    166166         *     @type array ...$0 {
     
    205205         * @param int    $user_id User ID.
    206206         * @param string $uuid    The password's UUID.
    207          * @return array|null The application password if found, null otherwise.
     207         * @return array|null {
     208         *     The application password if found, null otherwise.
     209         *
     210         *     @type string      $uuid      The unique identifier for the application password.
     211         *     @type string      $app_id    A UUID provided by the application to uniquely identify it.
     212         *     @type string      $name      The name of the application password.
     213         *     @type string      $password  A one-way hash of the password.
     214         *     @type int         $created   Unix timestamp of when the password was created.
     215         *     @type int|null    $last_used The Unix timestamp of the GMT date the application password was last used.
     216         *     @type string|null $last_ip   The IP address the application password was last used by.
     217         * }
    208218         */
    209219        public static function get_user_application_password( $user_id, $uuid ) {
     
    247257         * @param int    $user_id User ID.
    248258         * @param string $uuid    The password's UUID.
    249          * @param array  $update  Information about the application password to update.
     259         * @param array  $update  {
     260         *     Information about the application password to update.
     261         *
     262         *     @type string      $uuid      The unique identifier for the application password.
     263         *     @type string      $app_id    A UUID provided by the application to uniquely identify it.
     264         *     @type string      $name      The name of the application password.
     265         *     @type string      $password  A one-way hash of the password.
     266         *     @type int         $created   Unix timestamp of when the password was created.
     267         *     @type int|null    $last_used The Unix timestamp of the GMT date the application password was last used.
     268         *     @type string|null $last_ip   The IP address the application password was last used by.
     269         * }
    250270         * @return true|WP_Error True if successful, otherwise a WP_Error instance is returned on error.
    251271         */
     
    283303                         *
    284304                         * @param int   $user_id The user ID.
    285                          * @param array $item    The updated app password details.
     305                         * @param array $item    {
     306                         *     The updated application password details.
     307                         *
     308                         *     @type string      $uuid      The unique identifier for the application password.
     309                         *     @type string      $app_id    A UUID provided by the application to uniquely identify it.
     310                         *     @type string      $name      The name of the application password.
     311                         *     @type string      $password  A one-way hash of the password.
     312                         *     @type int         $created   Unix timestamp of when the password was created.
     313                         *     @type int|null    $last_used The Unix timestamp of the GMT date the application password was last used.
     314                         *     @type string|null $last_ip   The IP address the application password was last used by.
     315                         * }
    286316                         * @param array $update  The information to update.
    287317                         */
     
    405435         *
    406436         * @param int   $user_id   User ID.
    407          * @param array $passwords Application passwords.
    408          *
    409          * @return bool
     437         * @param array $passwords {
     438         *     The list of application passwords.
     439         *
     440         *     @type array ...$0 {
     441         *         @type string      $uuid      The unique identifier for the application password.
     442         *         @type string      $app_id    A UUID provided by the application to uniquely identify it.
     443         *         @type string      $name      The name of the application password.
     444         *         @type string      $password  A one-way hash of the password.
     445         *         @type int         $created   Unix timestamp of when the password was created.
     446         *         @type int|null    $last_used The Unix timestamp of the GMT date the application password was last used.
     447         *         @type string|null $last_ip   The IP address the application password was last used by.
     448         *     }
     449         * }
     450         * @return int|bool User meta ID if the key didn't exist (ie. this is the first time that an application password
     451         *                  has been saved for the user), true on successful update, false on failure or if the value passed
     452         *                  is the same as the one that is already in the database.
    410453         */
    411454        protected static function set_user_application_passwords( $user_id, $passwords ) {
  • trunk/src/wp-includes/class-wp-block.php

    r58398 r59009  
    115115         *
    116116         * @param array                  $block             {
    117          *     A representative array of a single parsed block object. See WP_Block_Parser_Block.
     117         *     An associative array of a single parsed block object. See WP_Block_Parser_Block.
    118118         *
    119119         *     @type string   $blockName    Name of block.
  • trunk/src/wp-includes/class-wp-http.php

    r57936 r59009  
    146146         *
    147147         * }
    148          * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
    149          *                        A WP_Error instance upon error.
     148         * @return array|WP_Error {
     149         *     Array of response data, or a WP_Error instance upon error.
     150         *
     151         *     @type \WpOrg\Requests\Utility\CaseInsensitiveDictionary $headers       Response headers keyed by name.
     152         *     @type string                                            $body          Response body.
     153         *     @type array                                             $response      {
     154         *         Array of HTTP response data.
     155         *
     156         *         @type int|false    $code    HTTP response status code.
     157         *         @type string|false $message HTTP response message.
     158         *     }
     159         *     @type WP_HTTP_Cookie[]                                  $cookies       Array of cookies set by the server.
     160         *     @type string|null                                       $filename      Optional. Filename of the response.
     161         *     @type WP_HTTP_Requests_Response|null                    $http_response Response object.
     162         * }
    150163         */
    151164        public function request( $url, $args = array() ) {
  • trunk/src/wp-includes/class-wp-site-query.php

    r58454 r59009  
    264264         *
    265265         * @param string|array $query Array or URL query string of parameters.
    266          * @return array|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids',
    267          *                   or the number of sites when 'count' is passed as a query var.
     266         * @return WP_Site[]|int[]|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids',
     267         *                             or the number of sites when 'count' is passed as a query var.
    268268         */
    269269        public function query( $query ) {
     
    280280         * @global wpdb $wpdb WordPress database abstraction object.
    281281         *
    282          * @return array|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids',
    283          *                   or the number of sites when 'count' is passed as a query var.
     282         * @return WP_Site[]|int[]|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids',
     283         *                             or the number of sites when 'count' is passed as a query var.
    284284         */
    285285        public function get_sites() {
     
    334334                 *              of the current WP_Site_Query instance.
    335335                 *
    336                  * @param array|int|null $site_data Return an array of site data to short-circuit WP's site query,
    337                  *                                  the site count as an integer if `$this->query_vars['count']` is set,
    338                  *                                  or null to run the normal queries.
    339                  * @param WP_Site_Query  $query     The WP_Site_Query instance, passed by reference.
     336                 * @param WP_Site[]|int[]|int|null $site_data Return an array of site data to short-circuit WP's site query,
     337                 *                                            the site count as an integer if `$this->query_vars['count']` is set,
     338                 *                                            or null to run the normal queries.
     339                 * @param WP_Site_Query            $query     The WP_Site_Query instance, passed by reference.
    340340                 */
    341341                $site_data = apply_filters_ref_array( 'sites_pre_query', array( $site_data, &$this ) );
  • trunk/src/wp-includes/http.php

    r58934 r59009  
    4646 *                     See WP_Http::request() for information on accepted arguments.
    4747 * @return array|WP_Error The response or WP_Error on failure.
     48 *                        See WP_Http::request() for information on return value.
    4849 */
    4950function wp_safe_remote_request( $url, $args = array() ) {
     
    7273 *                     See WP_Http::request() for information on accepted arguments.
    7374 * @return array|WP_Error The response or WP_Error on failure.
     75 *                        See WP_Http::request() for information on return value.
    7476 */
    7577function wp_safe_remote_get( $url, $args = array() ) {
     
    98100 *                     See WP_Http::request() for information on accepted arguments.
    99101 * @return array|WP_Error The response or WP_Error on failure.
     102 *                        See WP_Http::request() for information on return value.
    100103 */
    101104function wp_safe_remote_post( $url, $args = array() ) {
     
    124127 *                     See WP_Http::request() for information on accepted arguments.
    125128 * @return array|WP_Error The response or WP_Error on failure.
     129 *                        See WP_Http::request() for information on return value.
    126130 */
    127131function wp_safe_remote_head( $url, $args = array() ) {
     
    147151 * @param array  $args Optional. Request arguments. Default empty array.
    148152 *                     See WP_Http::request() for information on accepted arguments.
    149  * @return array|WP_Error {
    150  *     The response array or a WP_Error on failure.
    151  *
    152  *     @type string[]                       $headers       Array of response headers keyed by their name.
    153  *     @type string                         $body          Response body.
    154  *     @type array                          $response      {
    155  *         Data about the HTTP response.
    156  *
    157  *         @type int|false    $code    HTTP response code.
    158  *         @type string|false $message HTTP response message.
    159  *     }
    160  *     @type WP_HTTP_Cookie[]               $cookies       Array of response cookies.
    161  *     @type WP_HTTP_Requests_Response|null $http_response Raw HTTP response object.
    162  * }
     153 * @return array|WP_Error The response array or a WP_Error on failure.
     154 *                        See WP_Http::request() for information on return value.
    163155 */
    164156function wp_remote_request( $url, $args = array() ) {
     
    179171 *                     See WP_Http::request() for information on accepted arguments.
    180172 * @return array|WP_Error The response or WP_Error on failure.
     173 *                        See WP_Http::request() for information on return value.
    181174 */
    182175function wp_remote_get( $url, $args = array() ) {
     
    197190 *                     See WP_Http::request() for information on accepted arguments.
    198191 * @return array|WP_Error The response or WP_Error on failure.
     192 *                        See WP_Http::request() for information on return value.
    199193 */
    200194function wp_remote_post( $url, $args = array() ) {
     
    215209 *                     See WP_Http::request() for information on accepted arguments.
    216210 * @return array|WP_Error The response or WP_Error on failure.
     211 *                        See WP_Http::request() for information on return value.
    217212 */
    218213function wp_remote_head( $url, $args = array() ) {
  • trunk/src/wp-includes/ms-site.php

    r58962 r59009  
    440440 * @param string|array $args Optional. Array or string of arguments. See WP_Site_Query::__construct()
    441441 *                           for information on accepted arguments. Default empty array.
    442  * @return array|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids',
    443  *                   or the number of sites when 'count' is passed as a query var.
     442 * @return WP_Site[]|int[]|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids',
     443 *                             or the number of sites when 'count' is passed as a query var.
    444444 */
    445445function get_sites( $args = array() ) {
  • trunk/src/wp-includes/pluggable.php

    r58838 r59009  
    25652565if ( ! function_exists( 'wp_hash_password' ) ) :
    25662566        /**
    2567          * Creates a hash (encrypt) of a plain text password.
     2567         * Creates a hash of a plain text password.
    25682568         *
    25692569         * For integration with other applications, this function can be overwritten to
    2570          * instead use the other package password checking algorithm.
     2570         * instead use the other package password hashing algorithm.
    25712571         *
    25722572         * @since 2.5.0
     
    25922592if ( ! function_exists( 'wp_check_password' ) ) :
    25932593        /**
    2594          * Checks the plaintext password against the encrypted Password.
     2594         * Checks a plaintext password against a hashed password.
    25952595         *
    25962596         * Maintains compatibility between old version and the new cookie authentication
     
    26002600         *
    26012601         * For integration with other applications, this function can be overwritten to
    2602          * instead use the other package password checking algorithm.
     2602         * instead use the other package password hashing algorithm.
    26032603         *
    26042604         * @since 2.5.0
     
    27932793if ( ! function_exists( 'wp_set_password' ) ) :
    27942794        /**
    2795          * Updates the user's password with a new encrypted one.
     2795         * Updates the user's password with a new hashed one.
    27962796         *
    27972797         * For integration with other applications, this function can be overwritten to
  • trunk/src/wp-includes/post.php

    r58962 r59009  
    77957795 * @param int|WP_Post $post         Post ID or post object where thumbnail should be attached.
    77967796 * @param int         $thumbnail_id Thumbnail to attach.
    7797  * @return int|bool True on success, false on failure.
     7797 * @return int|bool Post meta ID if the key didn't exist (ie. this is the first time that
     7798 *                  a thumbnail has been saved for the post), true on successful update,
     7799 *                  false on failure or if the value passed is the same as the one that
     7800 *                  is already in the database.
    77987801 */
    77997802function set_post_thumbnail( $post, $thumbnail_id ) {
  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php

    r58783 r59009  
    517517                /*
    518518                 * Verify if the current user has edit_theme_options capability.
    519                  * This capability is required to edit/view/delete templates.
     519                 * This capability is required to edit/view/delete global styles.
    520520                 */
    521521                if ( ! current_user_can( 'edit_theme_options' ) ) {
     
    597597                /*
    598598                 * Verify if the current user has edit_theme_options capability.
    599                  * This capability is required to edit/view/delete templates.
     599                 * This capability is required to edit/view/delete global styles.
    600600                 */
    601601                if ( ! current_user_can( 'edit_theme_options' ) ) {
  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php

    r58783 r59009  
    103103
    104104        /**
    105          * Creates a single post.
     105         * Creates a single nav menu item.
    106106         *
    107107         * @since 5.9.0
     
    268268
    269269        /**
    270          * Deletes a single menu item.
     270         * Deletes a single nav menu item.
    271271         *
    272272         * @since 5.9.0
     
    318318
    319319        /**
    320          * Prepares a single post for create or update.
     320         * Prepares a single nav menu item for create or update.
    321321         *
    322322         * @since 5.9.0
     
    483483
    484484        /**
    485          * Prepares a single post output for response.
     485         * Prepares a single nav menu item output for response.
    486486         *
    487487         * @since 5.9.0
     
    679679
    680680        /**
    681          * Retrieves Link Description Objects that should be added to the Schema for the posts collection.
     681         * Retrieves Link Description Objects that should be added to the Schema for the nav menu items collection.
    682682         *
    683683         * @since 5.9.0
     
    706706
    707707        /**
    708          * Retrieves the term's schema, conforming to JSON Schema.
     708         * Retrieves the nav menu item's schema, conforming to JSON Schema.
    709709         *
    710710         * @since 5.9.0
     
    927927
    928928        /**
    929          * Retrieves the query params for the posts collection.
     929         * Retrieves the query params for the nav menu items collection.
    930930         *
    931931         * @since 5.9.0
Note: See TracChangeset for help on using the changeset viewer.