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

@@ -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 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[] $file          An array of data for a single file.
-	 * @param string $new_file      Filename of the newly-uploaded file.
+	 * @param string   $new_file      Filename of the newly-uploaded file.
-	 * @param string $type          File type.
+	 * @param string   $type          File type.
 	 */
 	$move_new_file = apply_filters( 'pre_move_uploaded_file', null, $file, $new_file, $type );
 

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

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 string|null $pre_render The pre-rendered content. Default null.
-	 * @param array  $block      The block being rendered.
+	 * @param array       $block      The block being rendered.
 	 */
 	$pre_render = apply_filters( 'pre_render_block', null, $block );
 	if ( ! is_null( $pre_render ) ) {

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 array                $parsed_args        HTTP request arguments.
-		 * @param string              $url      The request URL.
+		 * @param string               $url      The request URL.
 		 */
 		$pre = apply_filters( 'pre_http_request', false, $parsed_args, $url );
 

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 bool|null $override Whether to override the request result. Default null.
-		 * @param string $uri      URL to check.
+		 * @param string    $uri      URL to check.
-		 * @param array  $check    Associative array result of parsing the URI.
+		 * @param array     $check    Associative array result of parsing the request URI.
-		 * @param array  $home     Associative array result of parsing the site URL.
+		 * @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 ) ) {

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 string   $error The XML-RPC error message.
-			 * @param WP_User $user  WP_User object.
+			 * @param WP_Error $user  WP_Error object.
 			 */
 			$this->error = apply_filters( 'xmlrpc_login_error', $this->error, $user );
 			return false;

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 int|string|WP_Error $approved    The approval status. Accepts 1, 0, 'spam' or WP_Error.
-	 * @param array                $commentdata Comment data.
+	 * @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|null $new     The new comment count. Default null.
-	 * @param int $old     The old comment count.
+	 * @param int      $old     The old comment count.
-	 * @param int $post_id Post ID.
+	 * @param int      $post_id Post ID.
 	 */
 	$new = apply_filters( 'pre_wp_update_comment_count_now', null, $old, $post_id );
 

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.
+ * @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
+ * @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
+ *                   events were registered with the hook and arguments combination), false if
- *                  unscheduling one or more events fail.
+ *                   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 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 string         $hook Action hook, the execution of which will be unscheduled.
-	 * @param array      $args Arguments to pass to the hook's callback function.
+	 * @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
+ * @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.
+ *                   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 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.
+	 * @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 null|false|object $pre  Value to return instead. Default null to continue retrieving the event.
-	 * @param string    $hook      Action hook of 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.
+	 * @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
+	 *                                Although not passed to a callback, these arguments are used to uniquely identify
-	 *                             event.
+	 *                                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 );

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|null $converted_text The text to be converted. Default null.
-	 * @param string $text           The text prior to entity conversion.
+	 * @param string      $text           The text prior to entity conversion.
 	 */
 	$filtered = apply_filters( 'pre_ent2ncr', null, $text );
 	if ( null !== $filtered ) {

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|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|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            $handle       Name of the script to register a translation domain to.
-	 * @param string       $domain       The text domain.
+	 * @param string            $domain       The text domain.
 	 */
 	$translations = apply_filters( 'pre_load_script_translations', null, $file, $handle, $domain );
 

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,
+ * @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.
+ *                           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 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 Gravatar to retrieve. Accepts a user ID, Gravatar MD5 hash,
-	 *                            user email, WP_User object, WP_Post object, or WP_Comment object.
+	 *                           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 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 Gravatar to retrieve. Accepts a user ID, Gravatar MD5 hash,
-	 *                            user email, WP_User object, WP_Post object, or WP_Comment object.
+	 *                           user email, WP_User object, WP_Post object, or WP_Comment object.
 	 */
 	return apply_filters( 'get_avatar_data', $args, $id_or_email );
 }

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 ) {

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 null|false|WP_Site $site     Site value to return by path.
-	 * @param string            $domain   The requested domain.
+	 * @param string             $domain   The requested domain.
-	 * @param string            $path     The requested path, in full.
+	 * @param string             $path     The requested path, in full.
-	 * @param int|null          $segments The suggested number of paths to consult.
+	 * @param int|null           $segments The suggested number of paths to consult.
-	 *                                    Default null, meaning the entire path was to be consulted.
+	 *                                     Default null, meaning the entire path was to be consulted.
-	 * @param array             $paths    The paths to search for, based on $path and $segments.
+	 * @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 ) {

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 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,
+		 * @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.
+		 *                                 user email, WP_User object, WP_Post object, or WP_Comment object.
-		 * @param array  $args        Arguments passed to get_avatar_url(), after processing.
+		 * @param array       $args        Arguments passed to get_avatar_url(), after processing.
 		 */
 		$avatar = apply_filters( 'pre_get_avatar', null, $id_or_email, $args );
 

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 bool|null $delete       Whether to go forward with deletion.
-	 * @param WP_Post $post         Post object.
+	 * @param WP_Post   $post         Post object.
-	 * @param bool    $force_delete Whether to bypass the trash.
+	 * @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 bool|null $trash Whether to go forward with trashing.
-	 * @param WP_Post $post  Post object.
+	 * @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 bool|null $untrash Whether to go forward with untrashing.
-	 * @param WP_Post $post    Post object.
+	 * @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|null $override_slug Short-circuit return value.
-	 * @param string $slug          The desired slug (post_name).
+	 * @param string      $slug          The desired slug (post_name).
-	 * @param int    $post_ID       Post ID.
+	 * @param int         $post_ID       Post ID.
-	 * @param string $post_status   The post status.
+	 * @param string      $post_status   The post status.
-	 * @param string $post_type     Post type.
+	 * @param string      $post_type     Post type.
-	 * @param int    $post_parent   Post parent ID.
+	 * @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.
+ *                          'blog' uses the `post_date` field, which proxies to the timezone set for the site.
- *                          'gmt' uses the `post_modified_gmt` field.
+ *                          '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.
+	 * @param string|false $lastpostmodified The most recent time that a post was modified, in 'Y-m-d H:i:s' format, or
-	 *                                 Returning anything other than false will short-circuit the function.
+	 *                                       false. Returning anything other than false will short-circuit the function.
-	 * @param string $timezone         Location to use for getting the post modified date.
+	 * @param string       $timezone         Location to use for getting the post modified date.
-	 *                                 See get_lastpostdate() for accepted `$timezone` values.
+	 *                                       See get_lastpostdate() for accepted `$timezone` values.
-	 * @param string $post_type        The post type to check.
+	 * @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;

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.

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|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.
+	 * @param string          $taxonomy Taxonomy slug.
 	 */
 	$term = apply_filters( 'pre_insert_term', $term, $taxonomy );
 	if ( is_wp_error( $term ) ) {

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.

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|null $charset The character set to use. Default null.
-		 * @param string $table   The name of the table being checked.
+		 * @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|null $charset The character set to use. Default null.
-		 * @param string $table   The name of the table being checked.
+		 * @param string      $table   The name of the table being checked.
-		 * @param string $column  The name of the column 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 ) {