Commit 133d50d5a2 for wordpress.org
commit 133d50d5a2f60007d5c08926689115b256be849a
Author: John Blackbourn <johnbillion@git.wordpress.org>
Date: Tue Dec 16 20:21:37 2025 +0000
Docs: Miscellaneous improvements and corrections to inline documentation.
See #64224
Built from https://develop.svn.wordpress.org/trunk@61387
git-svn-id: http://core.svn.wordpress.org/trunk@60699 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-admin/includes/class-wp-upgrader.php b/wp-admin/includes/class-wp-upgrader.php
index d5a430d25a..eeb32b438c 100644
--- a/wp-admin/includes/class-wp-upgrader.php
+++ b/wp-admin/includes/class-wp-upgrader.php
@@ -590,7 +590,7 @@ class WP_Upgrader {
* Filters the source file location for the upgrade package.
*
* @since 2.8.0
- * @since 4.4.0 The $hook_extra parameter became available.
+ * @since 4.4.0 The `$hook_extra` parameter became available.
*
* @param string $source File source location.
* @param string $remote_source Remote file source location.
diff --git a/wp-admin/includes/post.php b/wp-admin/includes/post.php
index ab8fb62a7b..fdd873a888 100644
--- a/wp-admin/includes/post.php
+++ b/wp-admin/includes/post.php
@@ -1894,7 +1894,7 @@ function _admin_notice_post_locked() {
* Fires inside the post locked dialog before the buttons are displayed.
*
* @since 3.6.0
- * @since 5.4.0 The $user parameter was added.
+ * @since 5.4.0 The `$user` parameter was added.
*
* @param WP_Post $post Post object.
* @param WP_User $user The user with the lock for the post.
diff --git a/wp-includes/class-wp-customize-setting.php b/wp-includes/class-wp-customize-setting.php
index 95f6b26972..de2dbdadeb 100644
--- a/wp-includes/class-wp-customize-setting.php
+++ b/wp-includes/class-wp-customize-setting.php
@@ -765,7 +765,7 @@ class WP_Customize_Setting {
* functions for available hooks.
*
* @since 3.4.0
- * @since 4.6.0 Added the `$this` setting instance as the second parameter.
+ * @since 4.6.0 Added the `$setting` instance as the second parameter.
*
* @param mixed $default_value The setting default value. Default empty.
* @param WP_Customize_Setting $setting The setting instance.
diff --git a/wp-includes/class-wp-image-editor.php b/wp-includes/class-wp-image-editor.php
index 87a9d91f4f..d7fe151a0d 100644
--- a/wp-includes/class-wp-image-editor.php
+++ b/wp-includes/class-wp-image-editor.php
@@ -255,7 +255,7 @@ abstract class WP_Image_Editor {
* The WP_Image_Editor::set_quality() method has priority over the filter.
*
* @since 3.5.0
- * @since 6.8.0 Added the size parameter.
+ * @since 6.8.0 Added the `$size` parameter.
*
* @param int $quality Quality level between 1 (low) and 100 (high).
* @param string $mime_type Image mime type.
diff --git a/wp-includes/class-wp-query.php b/wp-includes/class-wp-query.php
index 07852fc8a5..d29c5a4375 100644
--- a/wp-includes/class-wp-query.php
+++ b/wp-includes/class-wp-query.php
@@ -1900,8 +1900,8 @@ class WP_Query {
* Fires after the query variable object is created, but before the actual query is run.
*
* Note: If using conditional tags, use the method versions within the passed instance
- * (e.g. $this->is_main_query() instead of is_main_query()). This is because the functions
- * like is_main_query() test against the global $wp_query instance, not the passed one.
+ * (e.g. `$query->is_main_query()` instead of `is_main_query()`). This is because the functions
+ * like `is_main_query()` test against the global `$wp_query` instance, not the passed one.
*
* @since 2.0.0
*
diff --git a/wp-includes/class-wp-user-query.php b/wp-includes/class-wp-user-query.php
index 014cfb2ac5..d704dc7034 100644
--- a/wp-includes/class-wp-user-query.php
+++ b/wp-includes/class-wp-user-query.php
@@ -851,7 +851,7 @@ class WP_User_Query {
* Filters SELECT FOUND_ROWS() query for the current WP_User_Query instance.
*
* @since 3.2.0
- * @since 5.1.0 Added the `$this` parameter.
+ * @since 5.1.0 Added the `$query` parameter.
*
* @global wpdb $wpdb WordPress database abstraction object.
*
diff --git a/wp-includes/class-wp-user.php b/wp-includes/class-wp-user.php
index 3b039ffb9d..687c910a08 100644
--- a/wp-includes/class-wp-user.php
+++ b/wp-includes/class-wp-user.php
@@ -654,7 +654,7 @@ class WP_User {
* Fires after the user's role has changed.
*
* @since 2.9.0
- * @since 3.6.0 Added $old_roles to include an array of the user's previous roles.
+ * @since 3.6.0 Added `$old_roles` to include an array of the user's previous roles.
*
* @param int $user_id The user ID.
* @param string $role The new role.
diff --git a/wp-includes/comment.php b/wp-includes/comment.php
index bb4abf2cd7..03fed10fa2 100644
--- a/wp-includes/comment.php
+++ b/wp-includes/comment.php
@@ -598,7 +598,7 @@ function wp_set_comment_cookies( $comment, $user, $cookies_consent = true ) {
* Filters the lifetime of the comment cookie in seconds.
*
* @since 2.8.0
- * @since 6.6.0 The default $seconds value changed from 30000000 to YEAR_IN_SECONDS.
+ * @since 6.6.0 The default `$seconds` value changed from 30000000 to YEAR_IN_SECONDS.
*
* @param int $seconds Comment cookie lifetime. Default YEAR_IN_SECONDS.
*/
diff --git a/wp-includes/cron.php b/wp-includes/cron.php
index afea4bce97..c6eab59a20 100644
--- a/wp-includes/cron.php
+++ b/wp-includes/cron.php
@@ -74,7 +74,7 @@ function wp_schedule_single_event( $timestamp, $hook, $args = array(), $wp_error
* Return true if the event was scheduled, false or a WP_Error if not.
*
* @since 5.1.0
- * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned.
+ * @since 5.7.0 The `$wp_error` parameter was added, and a WP_Error object can now be returned.
*
* @param null|bool|WP_Error $result The value to return instead. Default null to continue adding the event.
* @param object $event {
@@ -385,7 +385,7 @@ function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $
* rescheduled, false or a WP_Error if not.
*
* @since 5.1.0
- * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned.
+ * @since 5.7.0 The `$wp_error` parameter was added, and a WP_Error object can now be returned.
*
* @param null|bool|WP_Error $pre Value to return instead. Default null to continue adding the event.
* @param object $event {
@@ -482,7 +482,7 @@ function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = fa
* unscheduled, false or a WP_Error if not.
*
* @since 5.1.0
- * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned.
+ * @since 5.7.0 The `$wp_error` parameter was added, and a WP_Error object can now be returned.
*
* @param null|bool|WP_Error $pre Value to return instead. Default null to continue unscheduling the event.
* @param int $timestamp Unix timestamp (UTC) for when to run the event.
@@ -573,7 +573,7 @@ function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
* or a WP_Error if unscheduling one or more events fails.
*
* @since 5.1.0
- * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned.
+ * @since 5.7.0 The `$wp_error` parameter was added, and a WP_Error object can now be returned.
*
* @param null|int|false|WP_Error $pre Value to return instead. Default null to continue unscheduling the event.
* @param string $hook Action hook, the execution of which will be unscheduled.
@@ -664,7 +664,7 @@ function wp_unschedule_hook( $hook, $wp_error = false ) {
* on the value of the `$wp_error` parameter.
*
* @since 5.1.0
- * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned.
+ * @since 5.7.0 The `$wp_error` parameter was added, and a WP_Error object can now be returned.
*
* @param null|int|false|WP_Error $pre Value to return instead. Default null to continue unscheduling the hook.
* @param string $hook Action hook, the execution of which will be unscheduled.
@@ -853,6 +853,7 @@ function wp_next_scheduled( $hook, $args = array() ) {
* @type int $interval Optional. The interval time in seconds for the schedule. Only
* present for recurring events.
* }
+ * @param string $hook Action hook of the event.
* @param array $args Array containing each separate argument to pass to the hook
* callback function.
*/
diff --git a/wp-includes/functions.php b/wp-includes/functions.php
index 68a29f444f..ee10bb78e1 100644
--- a/wp-includes/functions.php
+++ b/wp-includes/functions.php
@@ -3300,7 +3300,7 @@ function wp_check_filetype_and_ext( $file, $filename, $mimes = null ) {
* Filters the "real" file type of the given file.
*
* @since 3.0.0
- * @since 5.1.0 The $real_mime parameter was added.
+ * @since 5.1.0 The `$real_mime` parameter was added.
*
* @param array $wp_check_filetype_and_ext {
* Values for the extension, mime type, and corrected filename.
@@ -3610,7 +3610,7 @@ function wp_get_ext_types() {
*/
function wp_filesize( $path ) {
/**
- * Filters the result of wp_filesize before the PHP function is run.
+ * Filters the result of wp_filesize() before the file_exists() PHP function is run.
*
* @since 6.0.0
*
@@ -6023,7 +6023,7 @@ function _doing_it_wrong( $function_name, $message, $version ) {
* Filters whether to trigger an error for _doing_it_wrong() calls.
*
* @since 3.1.0
- * @since 5.1.0 Added the $function_name, $message and $version parameters.
+ * @since 5.1.0 Added the `$function_name`, `$message`, and `$version` parameters.
*
* @param bool $trigger Whether to trigger the error for _doing_it_wrong() calls. Default true.
* @param string $function_name The function that was called.
diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php
index 1434d87a25..d1af2996bc 100644
--- a/wp-includes/link-template.php
+++ b/wp-includes/link-template.php
@@ -1625,7 +1625,7 @@ function get_edit_comment_link( $comment_id = 0, $context = 'display' ) {
* Filters the comment edit link.
*
* @since 2.3.0
- * @since 6.7.0 The $comment_id and $context parameters are now being passed to the filter.
+ * @since 6.7.0 The `$comment_id` and `$context` parameters are now being passed to the filter.
*
* @param string $location The edit link.
* @param int $comment_id Unique ID of the comment to generate an edit link.
diff --git a/wp-includes/load.php b/wp-includes/load.php
index 095affd677..434d836f67 100644
--- a/wp-includes/load.php
+++ b/wp-includes/load.php
@@ -1804,7 +1804,7 @@ function is_wp_error( $thing ) {
if ( $is_wp_error ) {
/**
- * Fires when `is_wp_error()` is called and its parameter is an instance of `WP_Error`.
+ * Fires when `is_wp_error()` is called and its parameter is an instance of WP_Error.
*
* @since 5.6.0
*
diff --git a/wp-includes/media.php b/wp-includes/media.php
index 229d22b849..5eb72d16c3 100644
--- a/wp-includes/media.php
+++ b/wp-includes/media.php
@@ -1618,7 +1618,7 @@ function wp_calculate_image_sizes( $size, $image_src = null, $image_meta = null,
$sizes = sprintf( '(max-width: %1$dpx) 100vw, %1$dpx', $width );
/**
- * Filters the output of 'wp_calculate_image_sizes()'.
+ * Filters the output of wp_calculate_image_sizes().
*
* @since 4.4.0
*
@@ -1742,7 +1742,7 @@ function wp_image_src_get_dimensions( $image_src, $image_meta, $attachment_id =
}
/**
- * Filters the 'wp_image_src_get_dimensions' value.
+ * Filters the wp_image_src_get_dimensions() value.
*
* @since 5.7.0
*
@@ -2156,7 +2156,7 @@ function wp_img_tag_add_loading_optimization_attrs( $image, $context ) {
if ( empty( $decoding_val ) ) {
/**
- * Filters the `decoding` attribute value to add to an image. Default `async`.
+ * Filters the `decoding` attribute value to add to an image. Default 'async'.
*
* Returning a falsey value will omit the attribute.
*
@@ -2199,7 +2199,7 @@ function wp_img_tag_add_loading_optimization_attrs( $image, $context ) {
if ( empty( $loading_val ) && $loading_attrs_enabled ) {
/**
- * Filters the `loading` attribute value to add to an image. Default `lazy`.
+ * Filters the `loading` attribute value to add to an image. Default 'lazy'.
*
* Returning `false` or an empty string will not add the attribute.
* Returning `true` will add the default value.
@@ -2383,7 +2383,7 @@ function wp_iframe_tag_add_loading_attr( $iframe, $context ) {
$value = isset( $optimization_attrs['loading'] ) ? $optimization_attrs['loading'] : false;
/**
- * Filters the `loading` attribute value to add to an iframe. Default `lazy`.
+ * Filters the `loading` attribute value to add to an iframe. Default 'lazy'.
*
* Returning `false` or an empty string will not add the attribute.
* Returning `true` will add the default value.
diff --git a/wp-includes/option.php b/wp-includes/option.php
index 7cb4736c28..735a1c6539 100644
--- a/wp-includes/option.php
+++ b/wp-includes/option.php
@@ -245,7 +245,7 @@ function get_option( $option, $default_value = false ) {
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
- * @since 1.5.0 As 'option_' . $setting
+ * @since 1.5.0 As `option_{$setting}`.
* @since 3.0.0
* @since 4.4.0 The `$option` parameter was added.
*
@@ -1325,10 +1325,11 @@ function wp_determine_option_autoload_value( $option, $value, $serialized_value,
*
* @since 6.6.0
*
- * @param bool|null $autoload The default autoload value to set. Returning true will be set as 'auto-on' in the
- * database, false will be set as 'auto-off', and null will be set as 'auto'.
- * @param string $option The passed option name.
- * @param mixed $value The passed option value to be saved.
+ * @param bool|null $autoload The default autoload value to set. Returning true will be set as 'auto-on' in the
+ * database, false will be set as 'auto-off', and null will be set as 'auto'.
+ * @param string $option The passed option name.
+ * @param mixed $value The passed option value to be saved.
+ * @param mixed $serialized_value The passed option value to be saved, in serialized form.
*/
$autoload = apply_filters( 'wp_default_autoload_value', null, $option, $value, $serialized_value );
if ( is_bool( $autoload ) ) {
@@ -2020,7 +2021,7 @@ function get_network_option( $network_id, $option, $default_value = false ) {
* Returning a value other than false from the filter will short-circuit retrieval
* and return that value instead.
*
- * @since 2.9.0 As 'pre_site_option_' . $key
+ * @since 2.9.0 As `pre_site_option_{$key}`.
* @since 3.0.0
* @since 4.4.0 The `$option` parameter was added.
* @since 4.7.0 The `$network_id` parameter was added.
@@ -2123,7 +2124,7 @@ function get_network_option( $network_id, $option, $default_value = false ) {
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
- * @since 2.9.0 As 'site_option_' . $key
+ * @since 2.9.0 As `site_option_{$key}`.
* @since 3.0.0
* @since 4.4.0 The `$option` parameter was added.
* @since 4.7.0 The `$network_id` parameter was added.
@@ -2172,7 +2173,7 @@ function add_network_option( $network_id, $option, $value ) {
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
- * @since 2.9.0 As 'pre_add_site_option_' . $key
+ * @since 2.9.0 As `pre_add_site_option_{$key}`.
* @since 3.0.0
* @since 4.4.0 The `$option` parameter was added.
* @since 4.7.0 The `$network_id` parameter was added.
@@ -2236,7 +2237,7 @@ function add_network_option( $network_id, $option, $value ) {
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
- * @since 2.9.0 As "add_site_option_{$key}"
+ * @since 2.9.0 As `add_site_option_{$key}`.
* @since 3.0.0
* @since 4.7.0 The `$network_id` parameter was added.
*
@@ -2342,7 +2343,7 @@ function delete_network_option( $network_id, $option ) {
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
- * @since 2.9.0 As "delete_site_option_{$key}"
+ * @since 2.9.0 As `delete_site_option_{$key}`.
* @since 3.0.0
* @since 4.7.0 The `$network_id` parameter was added.
*
diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php
index a2a062c70d..99c23540d8 100644
--- a/wp-includes/pluggable.php
+++ b/wp-includes/pluggable.php
@@ -655,7 +655,7 @@ if ( ! function_exists( 'wp_mail' ) ) :
$mail_data['phpmailer_exception_code'] = $e->getCode();
/**
- * Fires after a PHPMailer\PHPMailer\Exception is caught.
+ * Fires after a PHPMailer exception is caught.
*
* @since 4.4.0
*
@@ -1520,7 +1520,7 @@ if ( ! function_exists( 'wp_redirect' ) ) :
}
/**
- * Filters the X-Redirect-By header.
+ * Filters the value of the `X-Redirect-By` HTTP header.
*
* Allows applications to identify themselves when they're doing a redirect.
*
diff --git a/wp-includes/post.php b/wp-includes/post.php
index b646a2116c..a88d1afd57 100644
--- a/wp-includes/post.php
+++ b/wp-includes/post.php
@@ -1841,7 +1841,7 @@ function register_post_type( $post_type, $args = array() ) {
* Fires after a post type is registered.
*
* @since 3.3.0
- * @since 4.6.0 Converted the `$post_type` parameter to accept a `WP_Post_Type` object.
+ * @since 4.6.0 Converted the `$post_type` parameter to accept a WP_Post_Type object.
*
* @param string $post_type Post type.
* @param WP_Post_Type $post_type_object Arguments used to register the post type.
@@ -4792,7 +4792,7 @@ function wp_insert_post( $postarr, $wp_error = false, $fire_after_hooks = true )
// If a trashed post has the desired slug, change it and let this post have it.
if ( 'trash' !== $post_status && $post_name ) {
/**
- * Filters whether or not to add a `__trashed` suffix to trashed posts that match the name of the updated post.
+ * Filters whether or not to add a `__trashed` suffix to the name of trashed posts that match the name of the updated post.
*
* @since 5.4.0
*
@@ -6545,7 +6545,7 @@ function get_pages( $args = array() ) {
}
/**
- * Filters query arguments passed to WP_Query in get_pages.
+ * Filters query arguments passed to WP_Query in get_pages().
*
* @since 6.3.0
*
diff --git a/wp-includes/revision.php b/wp-includes/revision.php
index f292ad9150..2ae82b0511 100644
--- a/wp-includes/revision.php
+++ b/wp-includes/revision.php
@@ -379,7 +379,7 @@ function _wp_put_post_revision( $post = null, $autosave = false ) {
* Fires once a revision has been saved.
*
* @since 2.6.0
- * @since 6.4.0 The post_id parameter was added.
+ * @since 6.4.0 The `$post_id` parameter was added.
*
* @param int $revision_id Post revision ID.
* @param int $post_id Post ID.
diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php
index c314d474e6..003b414f4f 100644
--- a/wp-includes/taxonomy.php
+++ b/wp-includes/taxonomy.php
@@ -1013,7 +1013,7 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
* taxonomy.
*
* @since 2.3.0
- * @since 4.4.0 `$_term` is now a `WP_Term` object.
+ * @since 4.4.0 `$_term` is now a WP_Term object.
*
* @param WP_Term $_term Term object.
* @param string $taxonomy The taxonomy slug.
@@ -1032,7 +1032,7 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
* - `get_post_tag`
*
* @since 2.3.0
- * @since 4.4.0 `$_term` is now a `WP_Term` object.
+ * @since 4.4.0 `$_term` is now a WP_Term object.
*
* @param WP_Term $_term Term object.
* @param string $taxonomy The taxonomy slug.
diff --git a/wp-includes/user.php b/wp-includes/user.php
index 0e491d6660..9871f3b18c 100644
--- a/wp-includes/user.php
+++ b/wp-includes/user.php
@@ -3175,7 +3175,9 @@ function check_password_reset_key(
* Filters the return value of check_password_reset_key() when an
* old-style key or an expired key is used.
*
- * @since 3.7.0 Previously plain-text keys were stored in the database.
+ * Prior to 3.7, plain-text keys were stored in the database.
+ *
+ * @since 3.7.0
* @since 4.3.0 Previously key hashes were stored without an expiration time.
*
* @param WP_Error $return A WP_Error object denoting an expired key.
diff --git a/wp-includes/version.php b/wp-includes/version.php
index f5e0070679..81202f4acc 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.0-alpha-61386';
+$wp_version = '7.0-alpha-61387';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
diff --git a/wp-login.php b/wp-login.php
index 429032a43a..9423142701 100644
--- a/wp-login.php
+++ b/wp-login.php
@@ -397,13 +397,13 @@ function login_footer( $input_id = '' ) {
);
/**
- * Filters default arguments for the Languages select input on the login screen.
+ * Filters default arguments for the Language select input on the login screen.
*
* The arguments get passed to the wp_dropdown_languages() function.
*
* @since 5.9.0
*
- * @param array $args Arguments for the Languages select input on the login screen.
+ * @param array $args Arguments for the Language select input on the login screen.
*/
wp_dropdown_languages( apply_filters( 'login_language_dropdown_args', $args ) );
?>