From e36d1bcbd86619f64818b1952024346bdb722d9a Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Sat, 21 Sep 2019 17:41:57 +0000 Subject: [PATCH] Docs: Docblock corrections and improvements, mostly related to various `pre_*` filters. See #47110 Built from https://develop.svn.wordpress.org/trunk@46232 git-svn-id: http://core.svn.wordpress.org/trunk@46044 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/file.php | 8 ++-- wp-admin/includes/theme.php | 2 +- wp-includes/blocks.php | 4 +- wp-includes/class-http.php | 4 +- wp-includes/class-wp-http-proxy.php | 14 +++---- wp-includes/class-wp-xmlrpc-server.php | 4 +- wp-includes/comment.php | 12 +++--- wp-includes/cron.php | 34 ++++++++-------- wp-includes/formatting.php | 4 +- wp-includes/l10n.php | 8 ++-- wp-includes/link-template.php | 20 ++++----- wp-includes/ms-functions.php | 8 ++-- wp-includes/ms-load.php | 12 +++--- wp-includes/pluggable.php | 8 ++-- wp-includes/post.php | 56 +++++++++++++------------- wp-includes/shortcodes.php | 4 +- wp-includes/taxonomy.php | 9 +++-- wp-includes/version.php | 2 +- wp-includes/wp-db.php | 10 ++--- 19 files changed, 112 insertions(+), 111 deletions(-) diff --git a/wp-admin/includes/file.php b/wp-admin/includes/file.php index 93bdebfa8d..11977a8662 100644 --- a/wp-admin/includes/file.php +++ b/wp-admin/includes/file.php @@ -852,10 +852,10 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) { * * @since 4.9.0 * - * @param string $move_new_file If null (default) move the file after the upload. - * @param string $file An array of data for a single file. - * @param string $new_file Filename of the newly-uploaded file. - * @param string $type File type. + * @param mixed $move_new_file If null (default) move the file after the upload. + * @param string[] $file An array of data for a single file. + * @param string $new_file Filename of the newly-uploaded file. + * @param string $type File type. */ $move_new_file = apply_filters( 'pre_move_uploaded_file', null, $file, $new_file, $type ); diff --git a/wp-admin/includes/theme.php b/wp-admin/includes/theme.php index 7c9665b6aa..12035e1fc9 100644 --- a/wp-admin/includes/theme.php +++ b/wp-admin/includes/theme.php @@ -686,7 +686,7 @@ function wp_prepare_themes_for_js( $themes = null ) { * * @since 3.8.0 * - * @param array $prepared_themes Array of themes. + * @param array $prepared_themes Array of theme data. */ $prepared_themes = apply_filters( 'wp_prepare_themes_for_js', $prepared_themes ); $prepared_themes = array_values( $prepared_themes ); diff --git a/wp-includes/blocks.php b/wp-includes/blocks.php index 057648935f..e8647bf526 100644 --- a/wp-includes/blocks.php +++ b/wp-includes/blocks.php @@ -225,8 +225,8 @@ function render_block( $block ) { * * @since 5.1.0 * - * @param string $pre_render The pre-rendered content. Default null. - * @param array $block The block being rendered. + * @param string|null $pre_render The pre-rendered content. Default null. + * @param array $block The block being rendered. */ $pre_render = apply_filters( 'pre_render_block', null, $block ); if ( ! is_null( $pre_render ) ) { diff --git a/wp-includes/class-http.php b/wp-includes/class-http.php index 03511056ae..1d0d5074e5 100644 --- a/wp-includes/class-http.php +++ b/wp-includes/class-http.php @@ -251,8 +251,8 @@ class WP_Http { * @since 2.9.0 * * @param false|array|WP_Error $preempt Whether to preempt an HTTP request's return value. Default false. - * @param array $parsed_args HTTP request arguments. - * @param string $url The request URL. + * @param array $parsed_args HTTP request arguments. + * @param string $url The request URL. */ $pre = apply_filters( 'pre_http_request', false, $parsed_args, $url ); diff --git a/wp-includes/class-wp-http-proxy.php b/wp-includes/class-wp-http-proxy.php index 24a354e2c9..63a1186012 100644 --- a/wp-includes/class-wp-http-proxy.php +++ b/wp-includes/class-wp-http-proxy.php @@ -152,9 +152,9 @@ class WP_HTTP_Proxy { } /** - * Whether URL should be sent through the proxy server. + * Determines whether the request should be sent through a proxy. * - * We want to keep localhost and the site URL from being sent through the proxy server, because + * We want to keep localhost and the site URL from being sent through the proxy, because * some proxies can not handle this. We also have the constant available for defining other * hosts that won't be sent through the proxy. * @@ -181,17 +181,17 @@ class WP_HTTP_Proxy { $home = parse_url( get_option( 'siteurl' ) ); /** - * Filters whether to preempt sending the request through the proxy server. + * Filters whether to preempt sending the request through the proxy. * * Returning false will bypass the proxy; returning true will send * the request through the proxy. Returning null bypasses the filter. * * @since 3.5.0 * - * @param null $override Whether to override the request result. Default null. - * @param string $uri URL to check. - * @param array $check Associative array result of parsing the URI. - * @param array $home Associative array result of parsing the site URL. + * @param bool|null $override Whether to override the request result. Default null. + * @param string $uri URL to check. + * @param array $check Associative array result of parsing the request URI. + * @param array $home Associative array result of parsing the site URL. */ $result = apply_filters( 'pre_http_send_through_proxy', null, $uri, $check, $home ); if ( ! is_null( $result ) ) { diff --git a/wp-includes/class-wp-xmlrpc-server.php b/wp-includes/class-wp-xmlrpc-server.php index 47a2b031b2..abef0329ef 100644 --- a/wp-includes/class-wp-xmlrpc-server.php +++ b/wp-includes/class-wp-xmlrpc-server.php @@ -286,8 +286,8 @@ class wp_xmlrpc_server extends IXR_Server { * * @since 3.5.0 * - * @param string $error The XML-RPC error message. - * @param WP_User $user WP_User object. + * @param string $error The XML-RPC error message. + * @param WP_Error $user WP_Error object. */ $this->error = apply_filters( 'xmlrpc_login_error', $this->error, $user ); return false; diff --git a/wp-includes/comment.php b/wp-includes/comment.php index df0416fef8..fe5065dd9f 100644 --- a/wp-includes/comment.php +++ b/wp-includes/comment.php @@ -820,8 +820,8 @@ function wp_allow_comment( $commentdata, $avoid_die = false ) { * @since 4.9.0 Returning a WP_Error value from the filter will shortcircuit comment insertion and * allow skipping further processing. * - * @param bool|string|WP_Error $approved The approval status. Accepts 1, 0, 'spam' or WP_Error. - * @param array $commentdata Comment data. + * @param int|string|WP_Error $approved The approval status. Accepts 1, 0, 'spam' or WP_Error. + * @param array $commentdata Comment data. */ $approved = apply_filters( 'pre_comment_approved', $approved, $commentdata ); return $approved; @@ -2488,7 +2488,7 @@ function wp_update_comment_count( $post_id, $do_deferred = false ) { * @global wpdb $wpdb WordPress database abstraction object. * * @param int $post_id Post ID - * @return bool True on success, false on '0' $post_id or if post with ID does not exist. + * @return bool True on success, false if the post does not exist. */ function wp_update_comment_count_now( $post_id ) { global $wpdb; @@ -2512,9 +2512,9 @@ function wp_update_comment_count_now( $post_id ) { * * @since 4.5.0 * - * @param int $new The new comment count. Default null. - * @param int $old The old comment count. - * @param int $post_id Post ID. + * @param int|null $new The new comment count. Default null. + * @param int $old The old comment count. + * @param int $post_id Post ID. */ $new = apply_filters( 'pre_wp_update_comment_count_now', null, $old, $post_id ); diff --git a/wp-includes/cron.php b/wp-includes/cron.php index 2afe56b923..e010b86355 100644 --- a/wp-includes/cron.php +++ b/wp-includes/cron.php @@ -392,10 +392,10 @@ function wp_unschedule_event( $timestamp, $hook, $args = array() ) { * {@see 'pre_clear_scheduled_hook'} filter added to short-circuit the function. * * @param string $hook Action hook, the execution of which will be unscheduled. - * @param array $args Optional. Arguments that were to be passed to the hook's callback function. - * @return bool|int On success an integer indicating number of events unscheduled (0 indicates no - * events were registered with the hook and arguments combination), false if - * unscheduling one or more events fail. + * @param array $args Optional. Arguments that were to be passed to the hook's callback function. + * @return false|int On success an integer indicating number of events unscheduled (0 indicates no + * events were registered with the hook and arguments combination), false if + * unscheduling one or more events fail. */ function wp_clear_scheduled_hook( $hook, $args = array() ) { // Backward compatibility @@ -417,9 +417,9 @@ function wp_clear_scheduled_hook( $hook, $args = array() ) { * * @since 5.1.0 * - * @param null|array $pre Value to return instead. Default null to continue unscheduling the event. - * @param string $hook Action hook, the execution of which will be unscheduled. - * @param array $args Arguments to pass to the hook's callback function. + * @param null|int|false $pre Value to return instead. Default null to continue unscheduling the event. + * @param string $hook Action hook, the execution of which will be unscheduled. + * @param array $args Arguments to pass to the hook's callback function. */ $pre = apply_filters( 'pre_clear_scheduled_hook', null, $hook, $args ); if ( null !== $pre ) { @@ -461,8 +461,8 @@ function wp_clear_scheduled_hook( $hook, $args = array() ) { * @since 5.1.0 Return value added to indicate success or failure. * * @param string $hook Action hook, the execution of which will be unscheduled. - * @return bool|int On success an integer indicating number of events unscheduled (0 indicates no - * events were registered on the hook), false if unscheduling fails. + * @return false|int On success an integer indicating number of events unscheduled (0 indicates no + * events were registered on the hook), false if unscheduling fails. */ function wp_unschedule_hook( $hook ) { /** @@ -477,8 +477,8 @@ function wp_unschedule_hook( $hook ) { * * @since 5.1.0 * - * @param null|array $pre Value to return instead. Default null to continue unscheduling the hook. - * @param string $hook Action hook, the execution of which will be unscheduled. + * @param null|int|false $pre Value to return instead. Default null to continue unscheduling the hook. + * @param string $hook Action hook, the execution of which will be unscheduled. */ $pre = apply_filters( 'pre_unschedule_hook', null, $hook ); if ( null !== $pre ) { @@ -528,7 +528,7 @@ function wp_unschedule_hook( $hook ) { * Although not passed to a callback, these arguments are used to uniquely identify the * event, so they should be the same as those used when originally scheduling the event. * @param int|null $timestamp Optional. Unix timestamp (UTC) of the event. If not specified, the next scheduled event is returned. - * @return bool|object The event object. False if the event does not exist. + * @return false|object The event object. False if the event does not exist. */ function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) { /** @@ -542,11 +542,11 @@ function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) { * * @since 5.1.0 * - * @param null|bool $pre Value to return instead. Default null to continue retrieving the event. - * @param string $hook Action hook of the event. - * @param array $args Array containing each separate argument to pass to the hook's callback function. - * Although not passed to a callback, these arguments are used to uniquely identify the - * event. + * @param null|false|object $pre Value to return instead. Default null to continue retrieving the event. + * @param string $hook Action hook of the event. + * @param array $args Array containing each separate argument to pass to the hook's callback function. + * Although not passed to a callback, these arguments are used to uniquely identify + * the event. * @param int|null $timestamp Unix timestamp (UTC) of the event. Null to retrieve next scheduled event. */ $pre = apply_filters( 'pre_get_scheduled_event', null, $hook, $args, $timestamp ); diff --git a/wp-includes/formatting.php b/wp-includes/formatting.php index c1d1d581cb..dda39214e0 100644 --- a/wp-includes/formatting.php +++ b/wp-includes/formatting.php @@ -3836,8 +3836,8 @@ function ent2ncr( $text ) { * * @since 3.3.0 * - * @param null $converted_text The text to be converted. Default null. - * @param string $text The text prior to entity conversion. + * @param string|null $converted_text The text to be converted. Default null. + * @param string $text The text prior to entity conversion. */ $filtered = apply_filters( 'pre_ent2ncr', null, $text ); if ( null !== $filtered ) { diff --git a/wp-includes/l10n.php b/wp-includes/l10n.php index d77b15ee5b..419ebc3817 100644 --- a/wp-includes/l10n.php +++ b/wp-includes/l10n.php @@ -1053,10 +1053,10 @@ function load_script_translations( $file, $handle, $domain ) { * * @since 5.0.2 * - * @param string|false $translations JSON-encoded translation data. Default null. - * @param string|false $file Path to the translation file to load. False if there isn't one. - * @param string $handle Name of the script to register a translation domain to. - * @param string $domain The text domain. + * @param string|false|null $translations JSON-encoded translation data. Default null. + * @param string|false $file Path to the translation file to load. False if there isn't one. + * @param string $handle Name of the script to register a translation domain to. + * @param string $domain The text domain. */ $translations = apply_filters( 'pre_load_script_translations', null, $file, $handle, $domain ); diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php index f248c5b047..fa7188743f 100644 --- a/wp-includes/link-template.php +++ b/wp-includes/link-template.php @@ -3997,8 +3997,8 @@ 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, - * user email, WP_User object, WP_Post object, or WP_Comment object. + * @param mixed $id_or_email The Gravatar 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. * @@ -4020,7 +4020,7 @@ function is_avatar_comment_type( $comment_type ) { * plus a "found_avatar" guess. Pass as a reference. Default null. * @type string $extra_attr HTML attributes to insert in the IMG element. Is not sanitized. Default empty. * } - * @return array $processed_args { + * @return array { * Along with the arguments passed in `$args`, this will contain a couple of extra arguments. * * @type bool $found_avatar True if we were able to find an avatar for this user, @@ -4101,9 +4101,9 @@ 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, - * user email, WP_User object, WP_Post object, or WP_Comment object. + * @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, + * user email, WP_User object, WP_Post object, or WP_Comment object. */ $args = apply_filters( 'pre_get_avatar_data', $args, $id_or_email ); @@ -4193,7 +4193,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 Gravatar 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. */ @@ -4204,9 +4204,9 @@ 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, - * user email, WP_User object, WP_Post object, or WP_Comment object. + * @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, + * 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/wp-includes/ms-functions.php b/wp-includes/ms-functions.php index 5349754126..00b0a6c083 100644 --- a/wp-includes/ms-functions.php +++ b/wp-includes/ms-functions.php @@ -2426,19 +2426,19 @@ function wp_update_network_user_counts( $network_id = null ) { } /** - * Returns the space used by the current blog. + * Returns the space used by the current site. * * @since 3.5.0 * - * @return int Used space in megabytes + * @return int Used space in megabytes. */ function get_space_used() { /** - * Filters the amount of storage space used by the current site. + * Filters the amount of storage space used by the current site, in megabytes. * * @since 3.5.0 * - * @param int|bool $space_used The amount of used space, in megabytes. Default false. + * @param int|false $space_used The amount of used space, in megabytes. Default false. */ $space_used = apply_filters( 'pre_get_space_used', false ); if ( false === $space_used ) { diff --git a/wp-includes/ms-load.php b/wp-includes/ms-load.php index d1abc16048..e3ed91536a 100644 --- a/wp-includes/ms-load.php +++ b/wp-includes/ms-load.php @@ -203,12 +203,12 @@ function get_site_by_path( $domain, $path, $segments = null ) { * * @since 3.9.0 * - * @param null|bool|WP_Site $site Site value to return by path. - * @param string $domain The requested domain. - * @param string $path The requested path, in full. - * @param int|null $segments The suggested number of paths to consult. - * Default null, meaning the entire path was to be consulted. - * @param array $paths The paths to search for, based on $path and $segments. + * @param null|false|WP_Site $site Site value to return by path. + * @param string $domain The requested domain. + * @param string $path The requested path, in full. + * @param int|null $segments The suggested number of paths to consult. + * Default null, meaning the entire path was to be consulted. + * @param array $paths The paths to search for, based on $path and $segments. */ $pre = apply_filters( 'pre_get_site_by_path', null, $domain, $path, $segments, $paths ); if ( null !== $pre ) { diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php index 926f3e41b1..6386c95f62 100644 --- a/wp-includes/pluggable.php +++ b/wp-includes/pluggable.php @@ -2608,10 +2608,10 @@ if ( ! function_exists( 'get_avatar' ) ) : * * @since 4.2.0 * - * @param string $avatar HTML for the user's avatar. Default null. - * @param mixed $id_or_email The Gravatar 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_url(), after processing. + * @param string|null $avatar HTML for the user's avatar. Default null. + * @param mixed $id_or_email The Gravatar 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_url(), after processing. */ $avatar = apply_filters( 'pre_get_avatar', null, $id_or_email, $args ); diff --git a/wp-includes/post.php b/wp-includes/post.php index b40e94d8ce..491fc666a4 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -2935,9 +2935,9 @@ function wp_delete_post( $postid = 0, $force_delete = false ) { * * @since 4.4.0 * - * @param bool $delete Whether to go forward with deletion. - * @param WP_Post $post Post object. - * @param bool $force_delete Whether to bypass the trash. + * @param bool|null $delete Whether to go forward with deletion. + * @param WP_Post $post Post object. + * @param bool $force_delete Whether to bypass the trash. */ $check = apply_filters( 'pre_delete_post', null, $post, $force_delete ); if ( null !== $check ) { @@ -3104,8 +3104,8 @@ function wp_trash_post( $post_id = 0 ) { * * @since 4.9.0 * - * @param bool $trash Whether to go forward with trashing. - * @param WP_Post $post Post object. + * @param bool|null $trash Whether to go forward with trashing. + * @param WP_Post $post Post object. */ $check = apply_filters( 'pre_trash_post', null, $post ); if ( null !== $check ) { @@ -3173,8 +3173,8 @@ function wp_untrash_post( $post_id = 0 ) { * * @since 4.9.0 * - * @param bool $untrash Whether to go forward with untrashing. - * @param WP_Post $post Post object. + * @param bool|null $untrash Whether to go forward with untrashing. + * @param WP_Post $post Post object. */ $check = apply_filters( 'pre_untrash_post', null, $post ); if ( null !== $check ) { @@ -4284,12 +4284,12 @@ function wp_unique_post_slug( $slug, $post_ID, $post_status, $post_type, $post_p * * @since 5.1.0 * - * @param string $override_slug Short-circuit return value. - * @param string $slug The desired slug (post_name). - * @param int $post_ID Post ID. - * @param string $post_status The post status. - * @param string $post_type Post type. - * @param int $post_parent Post parent ID. + * @param string|null $override_slug Short-circuit return value. + * @param string $slug The desired slug (post_name). + * @param int $post_ID Post ID. + * @param string $post_status The post status. + * @param string $post_type Post type. + * @param int $post_parent Post parent ID. */ $override_slug = apply_filters( 'pre_wp_unique_post_slug', null, $slug, $post_ID, $post_status, $post_type, $post_parent ); if ( null !== $override_slug ) { @@ -6351,7 +6351,7 @@ function get_posts_by_author_sql( $post_type, $full = true, $post_author = null, } /** - * Retrieve the date that the last post was published. + * Retrieves the most recent time that a post on the site was published. * * The server timezone is the default and is the difference between GMT and * server time. The 'blog' value is the date when the last post was posted. The @@ -6362,15 +6362,15 @@ function get_posts_by_author_sql( $post_type, $full = true, $post_author = null, * * @param string $timezone Optional. The timezone for the timestamp. Accepts 'server', 'blog', or 'gmt'. * 'server' uses the server's internal timezone. - * 'blog' uses the `post_modified` field, which proxies to the timezone set for the site. - * 'gmt' uses the `post_modified_gmt` field. + * 'blog' uses the `post_date` field, which proxies to the timezone set for the site. + * 'gmt' uses the `post_date_gmt` field. * Default 'server'. * @param string $post_type Optional. The post type to check. Default 'any'. * @return string The date of the last post. */ function get_lastpostdate( $timezone = 'server', $post_type = 'any' ) { /** - * Filters the date the last post was published. + * Filters the most recent time that a post on the site was published. * * @since 2.3.0 * @@ -6382,7 +6382,7 @@ function get_lastpostdate( $timezone = 'server', $post_type = 'any' ) { } /** - * Get the timestamp of the last time any post was modified. + * Get the most recent time that a post on the site was modified. * * The server timezone is the default and is the difference between GMT and * server time. The 'blog' value is just when the last post was modified. The @@ -6395,7 +6395,7 @@ function get_lastpostdate( $timezone = 'server', $post_type = 'any' ) { * for information on accepted values. * Default 'server'. * @param string $post_type Optional. The post type to check. Default 'any'. - * @return string The timestamp. + * @return string The timestamp in 'Y-m-d H:i:s' format. */ function get_lastpostmodified( $timezone = 'server', $post_type = 'any' ) { /** @@ -6403,11 +6403,11 @@ function get_lastpostmodified( $timezone = 'server', $post_type = 'any' ) { * * @since 4.4.0 * - * @param string $lastpostmodified Date the last post was modified. - * Returning anything other than false will short-circuit the function. - * @param string $timezone Location to use for getting the post modified date. - * See get_lastpostdate() for accepted `$timezone` values. - * @param string $post_type The post type to check. + * @param string|false $lastpostmodified The most recent time that a post was modified, in 'Y-m-d H:i:s' format, or + * false. Returning anything other than false will short-circuit the function. + * @param string $timezone Location to use for getting the post modified date. + * See get_lastpostdate() for accepted `$timezone` values. + * @param string $post_type The post type to check. */ $lastpostmodified = apply_filters( 'pre_get_lastpostmodified', false, $timezone, $post_type ); if ( false !== $lastpostmodified ) { @@ -6422,11 +6422,11 @@ function get_lastpostmodified( $timezone = 'server', $post_type = 'any' ) { } /** - * Filters the date the last post was modified. + * Filters the most recent time that a post was modified. * * @since 2.3.0 * - * @param string $lastpostmodified Date the last post was modified. + * @param string $lastpostmodified The most recent time that a post was modified, in 'Y-m-d H:i:s' format. * @param string $timezone Location to use for getting the post modified date. * See get_lastpostdate() for accepted `$timezone` values. */ @@ -6434,7 +6434,7 @@ function get_lastpostmodified( $timezone = 'server', $post_type = 'any' ) { } /** - * Get the timestamp of the last time any post was modified or published. + * Gets the timestamp of the last time any post was modified or published. * * @since 3.1.0 * @since 4.4.0 The `$post_type` argument was added. @@ -6446,7 +6446,7 @@ function get_lastpostmodified( $timezone = 'server', $post_type = 'any' ) { * for information on accepted values. * @param string $field Post field to check. Accepts 'date' or 'modified'. * @param string $post_type Optional. The post type to check. Default 'any'. - * @return string|false The timestamp. + * @return string|false The timestamp in 'Y-m-d H:i:s' format, or false on error. */ function _get_last_post_time( $timezone, $field, $post_type = 'any' ) { global $wpdb; diff --git a/wp-includes/shortcodes.php b/wp-includes/shortcodes.php index 117cd23a30..ed042262cc 100644 --- a/wp-includes/shortcodes.php +++ b/wp-includes/shortcodes.php @@ -305,12 +305,12 @@ function do_shortcode_tag( $m ) { /** * Filters whether to call a shortcode callback. * - * Passing a truthy value to the filter will effectively short-circuit the + * Returning a non-false value from filter will short-circuit the * shortcode generation process, returning that value instead. * * @since 4.7.0 * - * @param bool|string $return Short-circuit return value. Either false or the value to replace the shortcode with. + * @param false|string $return Short-circuit return value. Either false or the value to replace the shortcode with. * @param string $tag Shortcode name. * @param array|string $attr Shortcode attributes array or empty string. * @param array $m Regular expression match array. diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index 3231285b1a..d93da9f138 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -1358,7 +1358,7 @@ function unregister_term_meta( $taxonomy, $meta_key ) { * @global wpdb $wpdb WordPress database abstraction object. * * @param int|string $term The term to check. Accepts term ID, slug, or name. - * @param string $taxonomy The taxonomy name to use + * @param string $taxonomy Optional. The taxonomy name to use. * @param int $parent Optional. ID of parent term under which to confine the exists search. * @return mixed Returns null if the term does not exist. Returns the term ID * if no taxonomy is specified and the term ID exists. Returns @@ -2097,7 +2097,7 @@ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) { * * @since 2.3.0 * - * @param string $term The term to add or update. + * @param string $term The term name to add or update. * @param string $taxonomy The taxonomy to which to add the term. * @param array|string $args { * Optional. Array or string of arguments for inserting a term. @@ -2117,13 +2117,14 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) { if ( ! taxonomy_exists( $taxonomy ) ) { return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); } + /** * Filters a term before it is sanitized and inserted into the database. * * @since 3.0.0 * - * @param string $term The term to add or update. - * @param string $taxonomy Taxonomy slug. + * @param string|WP_Error $term The term name to add or update, or a WP_Error object if there's an error. + * @param string $taxonomy Taxonomy slug. */ $term = apply_filters( 'pre_insert_term', $term, $taxonomy ); if ( is_wp_error( $term ) ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index 99fa0ec44e..b35eba73e3 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.3-alpha-46231'; +$wp_version = '5.3-alpha-46232'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php index 57471dc2ed..64da5169e1 100644 --- a/wp-includes/wp-db.php +++ b/wp-includes/wp-db.php @@ -2703,8 +2703,8 @@ class wpdb { * * @since 4.2.0 * - * @param string $charset The character set to use. Default null. - * @param string $table The name of the table being checked. + * @param string|null $charset The character set to use. Default null. + * @param string $table The name of the table being checked. */ $charset = apply_filters( 'pre_get_table_charset', null, $table ); if ( null !== $charset ) { @@ -2807,9 +2807,9 @@ class wpdb { * * @since 4.2.0 * - * @param string $charset The character set to use. Default null. - * @param string $table The name of the table being checked. - * @param string $column The name of the column being checked. + * @param string|null $charset The character set to use. Default null. + * @param string $table The name of the table being checked. + * @param string $column The name of the column being checked. */ $charset = apply_filters( 'pre_get_col_charset', null, $table, $column ); if ( null !== $charset ) {