From 8d745ce28d58275d07c84de05b24dfc985919529 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 11 Aug 2022 14:09:04 +0000 Subject: [PATCH] Docs: Miscellaneous inline documentation improvements. See #55646 git-svn-id: https://develop.svn.wordpress.org/trunk@53878 602fd350-edb4-49c9-b593-d223f7449a82 --- README.md | 6 +++--- src/wp-includes/class-wp-block-supports.php | 2 ++ src/wp-includes/class-wp-customize-control.php | 2 +- src/wp-includes/cron.php | 6 +++--- src/wp-includes/functions.php | 4 ++-- src/wp-includes/https-detection.php | 4 ++-- src/wp-includes/link-template.php | 12 ++++++------ src/wp-includes/ms-blogs.php | 2 +- src/wp-includes/post.php | 8 ++++---- 9 files changed, 24 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 5f6fc5951b..a69dab4e05 100644 --- a/README.md +++ b/README.md @@ -51,13 +51,13 @@ To stop the watcher, press `ctrl+c`. #### To run a [WP-CLI](https://make.wordpress.org/cli/handbook/) command ``` -npm run env:cli +npm run env:cli -- ``` -WP-CLI has a lot of [useful commands](https://developer.wordpress.org/cli/commands/) you can use to work on your WordPress site. Where the documentation mentions running `wp`, run `npm run env:cli` instead. For example: +WP-CLI has [many useful commands](https://developer.wordpress.org/cli/commands/) you can use to work on your WordPress site. Where the documentation mentions running `wp`, run `npm run env:cli --` instead. For example: ``` -npm run env:cli help +npm run env:cli -- help ``` #### To run the tests diff --git a/src/wp-includes/class-wp-block-supports.php b/src/wp-includes/class-wp-block-supports.php index 1cae5eb08c..703d03a629 100644 --- a/src/wp-includes/class-wp-block-supports.php +++ b/src/wp-includes/class-wp-block-supports.php @@ -72,6 +72,8 @@ class WP_Block_Supports { * * @since 5.6.0 * + * @link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/ + * * @param string $block_support_name Block support name. * @param array $block_support_config Array containing the properties of the block support. */ diff --git a/src/wp-includes/class-wp-customize-control.php b/src/wp-includes/class-wp-customize-control.php index dc6d4758df..63cc5f65ae 100644 --- a/src/wp-includes/class-wp-customize-control.php +++ b/src/wp-includes/class-wp-customize-control.php @@ -167,7 +167,7 @@ class WP_Customize_Control { * * Supplied `$args` override class property defaults. * - * If `$args['settings']` is not defined, use the $id as the setting ID. + * If `$args['settings']` is not defined, use the `$id` as the setting ID. * * @since 3.4.0 * diff --git a/src/wp-includes/cron.php b/src/wp-includes/cron.php index 1577dab9a6..f04088061a 100644 --- a/src/wp-includes/cron.php +++ b/src/wp-includes/cron.php @@ -1205,15 +1205,15 @@ function _set_cron_array( $cron, $wp_error = false ) { } /** - * Upgrade a Cron info array. + * Upgrade a cron info array. * - * This function upgrades the Cron info array to version 2. + * This function upgrades the cron info array to version 2. * * @since 2.1.0 * @access private * * @param array $cron Cron info array from _get_cron_array(). - * @return array An upgraded Cron info array. + * @return array An upgraded cron info array. */ function _upgrade_cron_array( $cron ) { if ( isset( $cron['version'] ) && 2 == $cron['version'] ) { diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php index 01f28bd08f..cf2d7ad146 100644 --- a/src/wp-includes/functions.php +++ b/src/wp-includes/functions.php @@ -4894,8 +4894,8 @@ function wp_array_slice_assoc( $array, $keys ) { * * @param array $array An array from which we want to retrieve some information. * @param array $path An array of keys describing the path with which to retrieve information. - * @param mixed $default The return value if the path does not exist within the array, - * or if `$array` or `$path` are not arrays. + * @param mixed $default Optional. The return value if the path does not exist within the array, + * or if `$array` or `$path` are not arrays. Default null. * @return mixed The value from the path specified. */ function _wp_array_get( $array, $path, $default = null ) { diff --git a/src/wp-includes/https-detection.php b/src/wp-includes/https-detection.php index a8af655a5b..9ef7b2bdc5 100644 --- a/src/wp-includes/https-detection.php +++ b/src/wp-includes/https-detection.php @@ -178,8 +178,8 @@ function wp_schedule_https_detection() { * @since 5.7.0 * @access private * - * @param array $request The Cron request arguments. - * @return array The filtered Cron request arguments. + * @param array $request The cron request arguments. + * @return array The filtered cron request arguments. */ function wp_cron_conditionally_prevent_sslverify( $request ) { if ( 'https' === wp_parse_url( $request['url'], PHP_URL_SCHEME ) ) { diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php index 7dcda3f9e6..038387161b 100644 --- a/src/wp-includes/link-template.php +++ b/src/wp-includes/link-template.php @@ -4161,7 +4161,7 @@ function the_shortlink( $text = '', $title = '', $before = '', $after = '' ) { * @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash, * user email, WP_User object, WP_Post object, or WP_Comment object. * @param array $args { - * Optional. Arguments to return instead of the default arguments. + * Optional. Arguments to use instead of the default arguments. * * @type int $size Height and width of the avatar in pixels. Default 96. * @type string $default URL for the default image or a default type. Accepts '404' (return @@ -4213,10 +4213,10 @@ function is_avatar_comment_type( $comment_type ) { * * @since 4.2.0 * - * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user ID, Gravatar MD5 hash, + * @param mixed $id_or_email The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash, * user email, WP_User object, WP_Post object, or WP_Comment object. * @param array $args { - * Optional. Arguments to return instead of the default arguments. + * Optional. Arguments to use instead of the default arguments. * * @type int $size Height and width of the avatar image file in pixels. Default 96. * @type int $height Display height of the avatar in pixels. Defaults to $size. @@ -4318,7 +4318,7 @@ function get_avatar_data( $id_or_email, $args = null ) { * @since 4.2.0 * * @param array $args Arguments passed to get_avatar_data(), after processing. - * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user ID, Gravatar MD5 hash, + * @param mixed $id_or_email The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash, * user email, WP_User object, WP_Post object, or WP_Comment object. */ $args = apply_filters( 'pre_get_avatar_data', $args, $id_or_email ); @@ -4409,7 +4409,7 @@ function get_avatar_data( $id_or_email, $args = null ) { * @since 4.2.0 * * @param string $url The URL of the avatar. - * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user ID, Gravatar MD5 hash, + * @param mixed $id_or_email The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash, * user email, WP_User object, WP_Post object, or WP_Comment object. * @param array $args Arguments passed to get_avatar_data(), after processing. */ @@ -4421,7 +4421,7 @@ function get_avatar_data( $id_or_email, $args = null ) { * @since 4.2.0 * * @param array $args Arguments passed to get_avatar_data(), after processing. - * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user ID, Gravatar MD5 hash, + * @param mixed $id_or_email The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash, * user email, WP_User object, WP_Post object, or WP_Comment object. */ return apply_filters( 'get_avatar_data', $args, $id_or_email ); diff --git a/src/wp-includes/ms-blogs.php b/src/wp-includes/ms-blogs.php index bb7ffb7dc7..ed30cc5fe8 100644 --- a/src/wp-includes/ms-blogs.php +++ b/src/wp-includes/ms-blogs.php @@ -75,7 +75,7 @@ function get_blogaddress_by_name( $blogname ) { } /** - * Retrieves a sites ID given its (subdomain or directory) slug. + * Retrieves a site's ID given its (subdomain or directory) slug. * * @since MU (3.0.0) * @since 4.7.0 Converted to use `get_sites()`. diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php index d53508f19b..d999c7bfeb 100644 --- a/src/wp-includes/post.php +++ b/src/wp-includes/post.php @@ -3217,14 +3217,14 @@ function get_post_mime_types() { /** * Checks a MIME-Type against a list. * - * If the wildcard_mime_types parameter is a string, it must be comma separated - * list. If the real_mime_types is a string, it is also comma separated to + * If the `$wildcard_mime_types` parameter is a string, it must be comma separated + * list. If the `$real_mime_types` is a string, it is also comma separated to * create the list. * * @since 2.5.0 * - * @param string|string[] $wildcard_mime_types Mime types, e.g. audio/mpeg or image (same as image/*) - * or flash (same as *flash*). + * @param string|string[] $wildcard_mime_types Mime types, e.g. `audio/mpeg`, `image` (same as `image/*`), + * or `flash` (same as `*flash*`). * @param string|string[] $real_mime_types Real post mime type values. * @return array array(wildcard=>array(real types)). */