diff --git a/wp-admin/includes/translation-install.php b/wp-admin/includes/translation-install.php index f18bbecd9c..67609836b9 100644 --- a/wp-admin/includes/translation-install.php +++ b/wp-admin/includes/translation-install.php @@ -14,7 +14,24 @@ * * @param string $type Type of translations. Accepts 'plugins', 'themes', 'core'. * @param array|object $args Translation API arguments. Optional. - * @return array|WP_Error On success an associative array of translations, WP_Error on failure. + * @return array|WP_Error { + * On success an associative array of translations, WP_Error on failure. + * + * @type array $translations { + * List of translations, each an array of data. + * + * @type array ...$0 { + * @type string $language Language code. + * @type string $version WordPress version. + * @type string $updated Date the translation was last updated, in MySQL datetime format. + * @type string $english_name English name of the language. + * @type string $native_name Native name of the language. + * @type string $package URL to download the translation package. + * @type string[] $iso Array of ISO language codes. + * @type array $strings Array of translated strings used in the installation process. + * } + * } + * } */ function translations_api( $type, $args = null ) { if ( ! in_array( $type, array( 'plugins', 'themes', 'core' ), true ) ) { @@ -100,7 +117,24 @@ function translations_api( $type, $args = null ) { * * @since 4.0.0 * - * @param array|WP_Error $res Response as an associative array or WP_Error. + * @param array|WP_Error $res { + * On success an associative array of translations, WP_Error on failure. + * + * @type array $translations { + * List of translations, each an array of data. + * + * @type array ...$0 { + * @type string $language Language code. + * @type string $version WordPress version. + * @type string $updated Date the translation was last updated, in MySQL datetime format. + * @type string $english_name English name of the language. + * @type string $native_name Native name of the language. + * @type string $package URL to download the translation package. + * @type string[] $iso Array of ISO language codes. + * @type array $strings Array of translated strings used in the installation process. + * } + * } + * } * @param string $type The type of translations being requested. * @param object $args Translation API arguments. */ @@ -114,8 +148,21 @@ function translations_api( $type, $args = null ) { * * @see translations_api() * - * @return array[] Array of translations, each an array of data, keyed by the language. If the API response results - * in an error, an empty array will be returned. + * @return array { + * Array of translations keyed by the language code, each an associative array of data. + * If the API response results in an error, an empty array will be returned. + * + * @type array ...$0 { + * @type string $language Language code. + * @type string $version WordPress version. + * @type string $updated Date the translation was last updated, in MySQL datetime format. + * @type string $english_name English name of the language. + * @type string $native_name Native name of the language. + * @type string $package URL to download the translation package. + * @type string[] $iso Array of ISO language codes. + * @type array $strings Array of translated strings used in the installation process. + * } + * } */ function wp_get_available_translations() { if ( ! wp_installing() ) { @@ -132,7 +179,7 @@ function wp_get_available_translations() { } $translations = array(); - // Key the array with the language code for now. + // Key the array with the language code. foreach ( $api['translations'] as $translation ) { $translations[ $translation['language'] ] = $translation; } diff --git a/wp-includes/blocks.php b/wp-includes/blocks.php index 9b24b989d4..1a8f3459c5 100644 --- a/wp-includes/blocks.php +++ b/wp-includes/blocks.php @@ -1432,7 +1432,7 @@ function get_comment_delimited_block_content( $block_name, $block_attributes, $b * @since 5.3.1 * * @param array $block { - * A representative array of a single parsed block object. See WP_Block_Parser_Block. + * An associative array of a single parsed block object. See WP_Block_Parser_Block. * * @type string $blockName Name of block. * @type array $attrs Attributes from block comment delimiters. @@ -1473,7 +1473,7 @@ function serialize_block( $block ) { * Array of block structures. * * @type array ...$0 { - * A representative array of a single parsed block object. See WP_Block_Parser_Block. + * An associative array of a single parsed block object. See WP_Block_Parser_Block. * * @type string $blockName Name of block. * @type array $attrs Attributes from block comment delimiters. @@ -1515,7 +1515,7 @@ function serialize_blocks( $blocks ) { * * @see serialize_block() * - * @param array $block A representative array of a single parsed block object. See WP_Block_Parser_Block. + * @param array $block An associative array of a single parsed block object. See WP_Block_Parser_Block. * @param callable $pre_callback Callback to run on each block in the tree before it is traversed and serialized. * It is called with the following arguments: &$block, $parent_block, $previous_block. * Its string return value will be prepended to the serialized block markup. @@ -1997,7 +1997,7 @@ function _excerpt_render_inner_blocks( $parsed_block, $allowed_blocks ) { * @global WP_Post $post The post to edit. * * @param array $parsed_block { - * A representative array of the block being rendered. See WP_Block_Parser_Block. + * An associative array of the block being rendered. See WP_Block_Parser_Block. * * @type string $blockName Name of block. * @type array $attrs Attributes from block comment delimiters. @@ -2021,7 +2021,7 @@ function render_block( $parsed_block ) { * * @param string|null $pre_render The pre-rendered content. Default null. * @param array $parsed_block { - * A representative array of the block being rendered. See WP_Block_Parser_Block. + * An associative array of the block being rendered. See WP_Block_Parser_Block. * * @type string $blockName Name of block. * @type array $attrs Attributes from block comment delimiters. @@ -2047,7 +2047,7 @@ function render_block( $parsed_block ) { * @since 5.9.0 The `$parent_block` parameter was added. * * @param array $parsed_block { - * A representative array of the block being rendered. See WP_Block_Parser_Block. + * An associative array of the block being rendered. See WP_Block_Parser_Block. * * @type string $blockName Name of block. * @type array $attrs Attributes from block comment delimiters. @@ -2095,7 +2095,7 @@ function render_block( $parsed_block ) { * * @param array $context Default context. * @param array $parsed_block { - * A representative array of the block being rendered. See WP_Block_Parser_Block. + * An associative array of the block being rendered. See WP_Block_Parser_Block. * * @type string $blockName Name of block. * @type array $attrs Attributes from block comment delimiters. @@ -2124,7 +2124,7 @@ function render_block( $parsed_block ) { * Array of block structures. * * @type array ...$0 { - * A representative array of a single parsed block object. See WP_Block_Parser_Block. + * An associative array of a single parsed block object. See WP_Block_Parser_Block. * * @type string $blockName Name of block. * @type array $attrs Attributes from block comment delimiters. diff --git a/wp-includes/class-wp-application-passwords.php b/wp-includes/class-wp-application-passwords.php index 49c4e58b6b..38ec4915de 100644 --- a/wp-includes/class-wp-application-passwords.php +++ b/wp-includes/class-wp-application-passwords.php @@ -71,7 +71,7 @@ class WP_Application_Passwords { * @return array|WP_Error { * Application password details, or a WP_Error instance if an error occurs. * - * @type string $0 The unhashed generated application password. + * @type string $0 The generated application password in plain text. * @type array $1 { * The details about the created password. * @@ -141,7 +141,7 @@ class WP_Application_Passwords { * @type null $last_used Null. * @type null $last_ip Null. * } - * @param string $new_password The unhashed generated application password. + * @param string $new_password The generated application password in plain text. * @param array $args { * Arguments used to create the application password. * @@ -161,7 +161,7 @@ class WP_Application_Passwords { * * @param int $user_id User ID. * @return array { - * The list of app passwords. + * The list of application passwords. * * @type array ...$0 { * @type string $uuid The unique identifier for the application password. @@ -204,7 +204,17 @@ class WP_Application_Passwords { * * @param int $user_id User ID. * @param string $uuid The password's UUID. - * @return array|null The application password if found, null otherwise. + * @return array|null { + * The application password if found, null otherwise. + * + * @type string $uuid The unique identifier for the application password. + * @type string $app_id A UUID provided by the application to uniquely identify it. + * @type string $name The name of the application password. + * @type string $password A one-way hash of the password. + * @type int $created Unix timestamp of when the password was created. + * @type int|null $last_used The Unix timestamp of the GMT date the application password was last used. + * @type string|null $last_ip The IP address the application password was last used by. + * } */ public static function get_user_application_password( $user_id, $uuid ) { $passwords = static::get_user_application_passwords( $user_id ); @@ -246,7 +256,17 @@ class WP_Application_Passwords { * * @param int $user_id User ID. * @param string $uuid The password's UUID. - * @param array $update Information about the application password to update. + * @param array $update { + * Information about the application password to update. + * + * @type string $uuid The unique identifier for the application password. + * @type string $app_id A UUID provided by the application to uniquely identify it. + * @type string $name The name of the application password. + * @type string $password A one-way hash of the password. + * @type int $created Unix timestamp of when the password was created. + * @type int|null $last_used The Unix timestamp of the GMT date the application password was last used. + * @type string|null $last_ip The IP address the application password was last used by. + * } * @return true|WP_Error True if successful, otherwise a WP_Error instance is returned on error. */ public static function update_application_password( $user_id, $uuid, $update = array() ) { @@ -282,7 +302,17 @@ class WP_Application_Passwords { * @since 5.6.0 * * @param int $user_id The user ID. - * @param array $item The updated app password details. + * @param array $item { + * The updated application password details. + * + * @type string $uuid The unique identifier for the application password. + * @type string $app_id A UUID provided by the application to uniquely identify it. + * @type string $name The name of the application password. + * @type string $password A one-way hash of the password. + * @type int $created Unix timestamp of when the password was created. + * @type int|null $last_used The Unix timestamp of the GMT date the application password was last used. + * @type string|null $last_ip The IP address the application password was last used by. + * } * @param array $update The information to update. */ do_action( 'wp_update_application_password', $user_id, $item, $update ); @@ -404,9 +434,22 @@ class WP_Application_Passwords { * @since 5.6.0 * * @param int $user_id User ID. - * @param array $passwords Application passwords. + * @param array $passwords { + * The list of application passwords. * - * @return bool + * @type array ...$0 { + * @type string $uuid The unique identifier for the application password. + * @type string $app_id A UUID provided by the application to uniquely identify it. + * @type string $name The name of the application password. + * @type string $password A one-way hash of the password. + * @type int $created Unix timestamp of when the password was created. + * @type int|null $last_used The Unix timestamp of the GMT date the application password was last used. + * @type string|null $last_ip The IP address the application password was last used by. + * } + * } + * @return int|bool User meta ID if the key didn't exist (ie. this is the first time that an application password + * has been saved for the user), true on successful update, false on failure or if the value passed + * is the same as the one that is already in the database. */ protected static function set_user_application_passwords( $user_id, $passwords ) { return update_user_meta( $user_id, static::USERMETA_KEY_APPLICATION_PASSWORDS, $passwords ); diff --git a/wp-includes/class-wp-block.php b/wp-includes/class-wp-block.php index c6ca8a3bd4..f7fd53dfc9 100644 --- a/wp-includes/class-wp-block.php +++ b/wp-includes/class-wp-block.php @@ -114,7 +114,7 @@ class WP_Block { * @since 5.5.0 * * @param array $block { - * A representative array of a single parsed block object. See WP_Block_Parser_Block. + * An associative array of a single parsed block object. See WP_Block_Parser_Block. * * @type string $blockName Name of block. * @type array $attrs Attributes from block comment delimiters. diff --git a/wp-includes/class-wp-http.php b/wp-includes/class-wp-http.php index ea8adde0ba..fde0f4355d 100644 --- a/wp-includes/class-wp-http.php +++ b/wp-includes/class-wp-http.php @@ -145,8 +145,21 @@ class WP_Http { * @type int $limit_response_size Size in bytes to limit the response to. Default null. * * } - * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. - * A WP_Error instance upon error. + * @return array|WP_Error { + * Array of response data, or a WP_Error instance upon error. + * + * @type \WpOrg\Requests\Utility\CaseInsensitiveDictionary $headers Response headers keyed by name. + * @type string $body Response body. + * @type array $response { + * Array of HTTP response data. + * + * @type int|false $code HTTP response status code. + * @type string|false $message HTTP response message. + * } + * @type WP_HTTP_Cookie[] $cookies Array of cookies set by the server. + * @type string|null $filename Optional. Filename of the response. + * @type WP_HTTP_Requests_Response|null $http_response Response object. + * } */ public function request( $url, $args = array() ) { $defaults = array( diff --git a/wp-includes/class-wp-site-query.php b/wp-includes/class-wp-site-query.php index 8c097fc17e..826bf76c78 100644 --- a/wp-includes/class-wp-site-query.php +++ b/wp-includes/class-wp-site-query.php @@ -263,8 +263,8 @@ class WP_Site_Query { * @since 4.6.0 * * @param string|array $query Array or URL query string of parameters. - * @return array|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids', - * or the number of sites when 'count' is passed as a query var. + * @return WP_Site[]|int[]|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids', + * or the number of sites when 'count' is passed as a query var. */ public function query( $query ) { $this->query_vars = wp_parse_args( $query ); @@ -279,8 +279,8 @@ class WP_Site_Query { * * @global wpdb $wpdb WordPress database abstraction object. * - * @return array|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids', - * or the number of sites when 'count' is passed as a query var. + * @return WP_Site[]|int[]|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids', + * or the number of sites when 'count' is passed as a query var. */ public function get_sites() { global $wpdb; @@ -333,10 +333,10 @@ class WP_Site_Query { * @since 5.6.0 The returned array of site data is assigned to the `sites` property * of the current WP_Site_Query instance. * - * @param array|int|null $site_data Return an array of site data to short-circuit WP's site query, - * the site count as an integer if `$this->query_vars['count']` is set, - * or null to run the normal queries. - * @param WP_Site_Query $query The WP_Site_Query instance, passed by reference. + * @param WP_Site[]|int[]|int|null $site_data Return an array of site data to short-circuit WP's site query, + * the site count as an integer if `$this->query_vars['count']` is set, + * or null to run the normal queries. + * @param WP_Site_Query $query The WP_Site_Query instance, passed by reference. */ $site_data = apply_filters_ref_array( 'sites_pre_query', array( $site_data, &$this ) ); diff --git a/wp-includes/http.php b/wp-includes/http.php index 240fd03795..fda090c4e8 100644 --- a/wp-includes/http.php +++ b/wp-includes/http.php @@ -45,6 +45,7 @@ function _wp_http_get_object() { * @param array $args Optional. Request arguments. Default empty array. * See WP_Http::request() for information on accepted arguments. * @return array|WP_Error The response or WP_Error on failure. + * See WP_Http::request() for information on return value. */ function wp_safe_remote_request( $url, $args = array() ) { $args['reject_unsafe_urls'] = true; @@ -71,6 +72,7 @@ function wp_safe_remote_request( $url, $args = array() ) { * @param array $args Optional. Request arguments. Default empty array. * See WP_Http::request() for information on accepted arguments. * @return array|WP_Error The response or WP_Error on failure. + * See WP_Http::request() for information on return value. */ function wp_safe_remote_get( $url, $args = array() ) { $args['reject_unsafe_urls'] = true; @@ -97,6 +99,7 @@ function wp_safe_remote_get( $url, $args = array() ) { * @param array $args Optional. Request arguments. Default empty array. * See WP_Http::request() for information on accepted arguments. * @return array|WP_Error The response or WP_Error on failure. + * See WP_Http::request() for information on return value. */ function wp_safe_remote_post( $url, $args = array() ) { $args['reject_unsafe_urls'] = true; @@ -123,6 +126,7 @@ function wp_safe_remote_post( $url, $args = array() ) { * @param array $args Optional. Request arguments. Default empty array. * See WP_Http::request() for information on accepted arguments. * @return array|WP_Error The response or WP_Error on failure. + * See WP_Http::request() for information on return value. */ function wp_safe_remote_head( $url, $args = array() ) { $args['reject_unsafe_urls'] = true; @@ -146,20 +150,8 @@ function wp_safe_remote_head( $url, $args = array() ) { * @param string $url URL to retrieve. * @param array $args Optional. Request arguments. Default empty array. * See WP_Http::request() for information on accepted arguments. - * @return array|WP_Error { - * The response array or a WP_Error on failure. - * - * @type string[] $headers Array of response headers keyed by their name. - * @type string $body Response body. - * @type array $response { - * Data about the HTTP response. - * - * @type int|false $code HTTP response code. - * @type string|false $message HTTP response message. - * } - * @type WP_HTTP_Cookie[] $cookies Array of response cookies. - * @type WP_HTTP_Requests_Response|null $http_response Raw HTTP response object. - * } + * @return array|WP_Error The response array or a WP_Error on failure. + * See WP_Http::request() for information on return value. */ function wp_remote_request( $url, $args = array() ) { $http = _wp_http_get_object(); @@ -178,6 +170,7 @@ function wp_remote_request( $url, $args = array() ) { * @param array $args Optional. Request arguments. Default empty array. * See WP_Http::request() for information on accepted arguments. * @return array|WP_Error The response or WP_Error on failure. + * See WP_Http::request() for information on return value. */ function wp_remote_get( $url, $args = array() ) { $http = _wp_http_get_object(); @@ -196,6 +189,7 @@ function wp_remote_get( $url, $args = array() ) { * @param array $args Optional. Request arguments. Default empty array. * See WP_Http::request() for information on accepted arguments. * @return array|WP_Error The response or WP_Error on failure. + * See WP_Http::request() for information on return value. */ function wp_remote_post( $url, $args = array() ) { $http = _wp_http_get_object(); @@ -214,6 +208,7 @@ function wp_remote_post( $url, $args = array() ) { * @param array $args Optional. Request arguments. Default empty array. * See WP_Http::request() for information on accepted arguments. * @return array|WP_Error The response or WP_Error on failure. + * See WP_Http::request() for information on return value. */ function wp_remote_head( $url, $args = array() ) { $http = _wp_http_get_object(); diff --git a/wp-includes/ms-site.php b/wp-includes/ms-site.php index 71d61cd6da..b1d50940a2 100644 --- a/wp-includes/ms-site.php +++ b/wp-includes/ms-site.php @@ -439,8 +439,8 @@ function update_sitemeta_cache( $site_ids ) { * * @param string|array $args Optional. Array or string of arguments. See WP_Site_Query::__construct() * for information on accepted arguments. Default empty array. - * @return array|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids', - * or the number of sites when 'count' is passed as a query var. + * @return WP_Site[]|int[]|int List of WP_Site objects, a list of site IDs when 'fields' is set to 'ids', + * or the number of sites when 'count' is passed as a query var. */ function get_sites( $args = array() ) { $query = new WP_Site_Query(); diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php index 8380a59724..690c0fe4bc 100644 --- a/wp-includes/pluggable.php +++ b/wp-includes/pluggable.php @@ -2564,10 +2564,10 @@ endif; if ( ! function_exists( 'wp_hash_password' ) ) : /** - * Creates a hash (encrypt) of a plain text password. + * Creates a hash of a plain text password. * * For integration with other applications, this function can be overwritten to - * instead use the other package password checking algorithm. + * instead use the other package password hashing algorithm. * * @since 2.5.0 * @@ -2591,7 +2591,7 @@ endif; if ( ! function_exists( 'wp_check_password' ) ) : /** - * Checks the plaintext password against the encrypted Password. + * Checks a plaintext password against a hashed password. * * Maintains compatibility between old version and the new cookie authentication * protocol using PHPass library. The $hash parameter is the encrypted password @@ -2599,7 +2599,7 @@ if ( ! function_exists( 'wp_check_password' ) ) : * against the already encrypted password to see if they match. * * For integration with other applications, this function can be overwritten to - * instead use the other package password checking algorithm. + * instead use the other package password hashing algorithm. * * @since 2.5.0 * @@ -2792,7 +2792,7 @@ endif; if ( ! function_exists( 'wp_set_password' ) ) : /** - * Updates the user's password with a new encrypted one. + * Updates the user's password with a new hashed one. * * For integration with other applications, this function can be overwritten to * instead use the other package password checking algorithm. diff --git a/wp-includes/post.php b/wp-includes/post.php index df4aa1c32f..725433939e 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -7794,7 +7794,10 @@ function wp_check_post_hierarchy_for_loops( $post_parent, $post_id ) { * * @param int|WP_Post $post Post ID or post object where thumbnail should be attached. * @param int $thumbnail_id Thumbnail to attach. - * @return int|bool True on success, false on failure. + * @return int|bool Post meta ID if the key didn't exist (ie. this is the first time that + * a thumbnail has been saved for the post), true on successful update, + * false on failure or if the value passed is the same as the one that + * is already in the database. */ function set_post_thumbnail( $post, $thumbnail_id ) { $post = get_post( $post ); diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php index e3057e75d8..8be3aedd9a 100644 --- a/wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php +++ b/wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php @@ -516,7 +516,7 @@ class WP_REST_Global_Styles_Controller extends WP_REST_Posts_Controller { public function get_theme_item_permissions_check( $request ) { /* * Verify if the current user has edit_theme_options capability. - * This capability is required to edit/view/delete templates. + * This capability is required to edit/view/delete global styles. */ if ( ! current_user_can( 'edit_theme_options' ) ) { return new WP_Error( @@ -596,7 +596,7 @@ class WP_REST_Global_Styles_Controller extends WP_REST_Posts_Controller { public function get_theme_items_permissions_check( $request ) { /* * Verify if the current user has edit_theme_options capability. - * This capability is required to edit/view/delete templates. + * This capability is required to edit/view/delete global styles. */ if ( ! current_user_can( 'edit_theme_options' ) ) { return new WP_Error( diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php index 9fbaa95371..ee69643813 100644 --- a/wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php +++ b/wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php @@ -102,7 +102,7 @@ class WP_REST_Menu_Items_Controller extends WP_REST_Posts_Controller { } /** - * Creates a single post. + * Creates a single nav menu item. * * @since 5.9.0 * @@ -267,7 +267,7 @@ class WP_REST_Menu_Items_Controller extends WP_REST_Posts_Controller { } /** - * Deletes a single menu item. + * Deletes a single nav menu item. * * @since 5.9.0 * @@ -317,7 +317,7 @@ class WP_REST_Menu_Items_Controller extends WP_REST_Posts_Controller { } /** - * Prepares a single post for create or update. + * Prepares a single nav menu item for create or update. * * @since 5.9.0 * @@ -482,7 +482,7 @@ class WP_REST_Menu_Items_Controller extends WP_REST_Posts_Controller { } /** - * Prepares a single post output for response. + * Prepares a single nav menu item output for response. * * @since 5.9.0 * @@ -678,7 +678,7 @@ class WP_REST_Menu_Items_Controller extends WP_REST_Posts_Controller { } /** - * Retrieves Link Description Objects that should be added to the Schema for the posts collection. + * Retrieves Link Description Objects that should be added to the Schema for the nav menu items collection. * * @since 5.9.0 * @@ -705,7 +705,7 @@ class WP_REST_Menu_Items_Controller extends WP_REST_Posts_Controller { } /** - * Retrieves the term's schema, conforming to JSON Schema. + * Retrieves the nav menu item's schema, conforming to JSON Schema. * * @since 5.9.0 * @@ -926,7 +926,7 @@ class WP_REST_Menu_Items_Controller extends WP_REST_Posts_Controller { } /** - * Retrieves the query params for the posts collection. + * Retrieves the query params for the nav menu items collection. * * @since 5.9.0 * diff --git a/wp-includes/version.php b/wp-includes/version.php index b4ef637d6d..3564ae8c90 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.7-alpha-59008'; +$wp_version = '6.7-alpha-59009'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.