WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
John Blackbourn 2019-09-21 17:41:57 +00:00
parent 123b4475b0
commit e36d1bcbd8
19 changed files with 112 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
wp-admin/includes/file.php
View File

@ -852,8 +852,8 @@ 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 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.
*/

2
wp-admin/includes/theme.php
View File

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

2
wp-includes/blocks.php
View File

@ -225,7 +225,7 @@ 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.
*/
$pre_render = apply_filters( 'pre_render_block', null, $block );

10
wp-includes/class-wp-http-proxy.php
View File

@ -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,16 +181,16 @@ 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 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.
*/
$result = apply_filters( 'pre_http_send_through_proxy', null, $uri, $check, $home );

2
wp-includes/class-wp-xmlrpc-server.php
View File

@ -287,7 +287,7 @@ 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 WP_Error $user WP_Error object.
*/
$this->error = apply_filters( 'xmlrpc_login_error', $this->error, $user );
return false;

6
wp-includes/comment.php
View File

@ -820,7 +820,7 @@ 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.
*/
$approved = apply_filters( 'pre_comment_approved', $approved, $commentdata );
@ -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,7 +2512,7 @@ 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 $post_id Post ID.
*/

16
wp-includes/cron.php
View File

@ -393,7 +393,7 @@ function wp_unschedule_event( $timestamp, $hook, $args = array() ) {
*
* @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
* @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.
*/
@ -417,7 +417,7 @@ 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 array $args Arguments to pass to the hook's callback function.
*/
@ -461,7 +461,7 @@ 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.
*/
function wp_unschedule_hook( $hook ) {
@ -477,7 +477,7 @@ 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.
*/
$pre = apply_filters( 'pre_unschedule_hook', null, $hook );
@ -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 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.
* 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 );

2
wp-includes/formatting.php
View File

@ -3836,7 +3836,7 @@ 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.
*/
$filtered = apply_filters( 'pre_ent2ncr', null, $text );

2
wp-includes/l10n.php
View File

@ -1053,7 +1053,7 @@ 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 $handle Name of the script to register a translation domain to.
* @param string $domain The text domain.

10
wp-includes/link-template.php
View File

@ -3997,7 +3997,7 @@ 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.
* @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,
@ -4102,7 +4102,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 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.
*/
@ -4205,7 +4205,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 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 );

8
wp-includes/ms-functions.php
View File

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

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

@ -203,7 +203,7 @@ 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 $path The requested path, in full.
* @param int|null $segments The suggested number of paths to consult.

2
wp-includes/pluggable.php
View File

@ -2608,7 +2608,7 @@ 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,
* user email, WP_User object, WP_Post object, or WP_Comment object.
* @param array $args Arguments passed to get_avatar_url(), after processing.

32
wp-includes/post.php
View File

@ -2935,7 +2935,7 @@ 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 bool $force_delete Whether to bypass the trash.
*/
@ -3104,7 +3104,7 @@ 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.
*/
$check = apply_filters( 'pre_trash_post', null, $post );
@ -3173,7 +3173,7 @@ 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.
*/
$check = apply_filters( 'pre_untrash_post', null, $post );
@ -4284,7 +4284,7 @@ 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 int $post_ID Post ID.
* @param string $post_status The post status.
@ -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,8 +6403,8 @@ 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|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.
@ -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;

4
wp-includes/shortcodes.php
View File

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

7
wp-includes/taxonomy.php
View File

@ -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,12 +2117,13 @@ 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.
*/
$term = apply_filters( 'pre_insert_term', $term, $taxonomy );

2
wp-includes/version.php
View File

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

4
wp-includes/wp-db.php
View File

@ -2703,7 +2703,7 @@ 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.
*/
$charset = apply_filters( 'pre_get_table_charset', null, $table );
@ -2807,7 +2807,7 @@ 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 $column The name of the column being checked.
*/