Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-12-22 09:07:59 +01:00
Code Issues Projects Releases Wiki Activity

Docs: Various docblock improvements and corrections.

Browse Source 
See #61608

Built from https://develop.svn.wordpress.org/trunk@59009


git-svn-id: http://core.svn.wordpress.org/trunk@58405 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
John Blackbourn 2024-09-11 12:08:19 +00:00
parent 2f943897c9
commit 87fd392188
13 changed files with 165 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
wp-admin/includes/translation-install.php
View File

@ -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;
}

16
wp-includes/blocks.php
View File

@ -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.

59
wp-includes/class-wp-application-passwords.php
View File

@ -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 );

2
wp-includes/class-wp-block.php
View File

@ -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.

17
wp-includes/class-wp-http.php
View File

@ -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(

6
wp-includes/class-wp-site-query.php
View File

@ -263,7 +263,7 @@ 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',
* @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 ) {
@ -279,7 +279,7 @@ 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',
* @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() {
@ -333,7 +333,7 @@ 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,
* @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.

23
wp-includes/http.php
View File

@ -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();

2
wp-includes/ms-site.php
View File

@ -439,7 +439,7 @@ 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',
* @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() ) {

10
wp-includes/pluggable.php
View File

@ -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.

5
wp-includes/post.php
View File

@ -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 );

4
wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php
View File

@ -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(

14
wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php
View File

@ -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
*

2
wp-includes/version.php
View File

@ -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.