Skip to content
Permalink
Browse files

Docs: Docblock corrections and improvements, mostly related to variou…

…s `pre_*` filters.

See #47110


git-svn-id: https://develop.svn.wordpress.org/trunk@46232 602fd350-edb4-49c9-b593-d223f7449a82
  • Loading branch information...
johnbillion committed Sep 21, 2019
1 parent 144c5f7 commit 6bd7097626c15aa331b23ad0c9f1692c161deddb
@@ -852,10 +852,10 @@ function wp_handle_upload_error( &$file, $message ) {
*
* @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 );
@@ -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 );
@@ -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 ) ) {
@@ -251,8 +251,8 @@ public function request( $url, $args = array() ) {
* @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 );
@@ -152,9 +152,9 @@ public function authentication_header() {
}
/**
* 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 @@ public function send_through_proxy( $uri ) {
$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 ) ) {
@@ -286,8 +286,8 @@ public function login( $username, $password ) {
*
* @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;
@@ -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 );
@@ -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 );
@@ -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 ) {
@@ -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 );
@@ -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 );
}
@@ -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 ) {
@@ -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 ) {
@@ -2608,10 +2608,10 @@ function get_avatar( $id_or_email, $size = 96, $default = '', $alt = '', $args =
*
* @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 );

0 comments on commit 6bd7097

Please sign in to comment.
You can’t perform that action at this time.