WordPress-C/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2025-02-16 11:35:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Standardize on "Returning a value from the filter" vs. "Passing a value to the filter".

Browse Source 
The filter is the callback function added with `add_filter()`, therefore the hook passes a value to the filter, and the filter returns a value to change its behaviour.

The documentation is referring to the latter.

Props johnbillion.
See #49572, #16557.
Built from https://develop.svn.wordpress.org/trunk@48185


git-svn-id: http://core.svn.wordpress.org/trunk@47954 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov 2020-06-26 18:49:09 +00:00
parent eb9a6c9690
commit 40c389c95e
18 changed files with 44 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
wp-admin/includes/export.php
View File

@ -328,7 +328,7 @@ function export_wp( $args = array() ) {
/**
* Filters whether to selectively skip term meta used for WXR exports.
*
* Returning a truthy value to the filter will skip the current meta
* Returning a truthy value from the filter will skip the current meta
* object from being exported.
*
* @since 4.6.0
@ -595,7 +595,7 @@ function export_wp( $args = array() ) {
/**
* Filters whether to selectively skip post meta used for WXR exports.
*
* Returning a truthy value to the filter will skip the current meta
* Returning a truthy value from the filter will skip the current meta
* object from being exported.
*
* @since 3.3.0
@ -638,7 +638,7 @@ function export_wp( $args = array() ) {
/**
* Filters whether to selectively skip comment meta used for WXR exports.
*
* Returning a truthy value to the filter will skip the current meta
* Returning a truthy value from the filter will skip the current meta
* object from being exported.
*
* @since 4.0.0

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

@ -880,8 +880,8 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) {
/**
* Filters whether to short-circuit moving the uploaded file after passing all checks.
*
* If a non-null value is passed to the filter, moving the file and any related error
* reporting will be completely skipped.
* If a non-null value is returned from the filter, moving the file and any related
* error reporting will be completely skipped.
*
* @since 4.9.0
*

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

@ -208,7 +208,7 @@ function image_add_caption( $html, $id, $caption, $title, $align, $url, $size, $
*
* @since 2.6.0
*
* @param bool $bool Whether to disable appending captions. Returning true to the filter
* @param bool $bool Whether to disable appending captions. Returning true from the filter
* will disable captions. Default empty string.
*/
if ( empty( $caption ) || apply_filters( 'disable_captions', '' ) ) {

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

@ -695,7 +695,7 @@ function set_screen_options() {
* The filter can also be used to modify non-standard [items]_per_page
* settings. See the parent function for a full list of standard options.
*
* Returning false to the filter will skip saving the current option.
* Returning false from the filter will skip saving the current option.
*
* @since 2.8.0
* @since 5.4.2 Only applied to options ending with '_page',
@ -716,7 +716,7 @@ function set_screen_options() {
*
* The dynamic portion of the hook, `$option`, refers to the option name.
*
* Returning false to the filter will skip saving the current option.
* Returning false from the filter will skip saving the current option.
*
* @since 5.4.2
*

2
wp-includes/blocks.php
View File

@ -658,7 +658,7 @@ function render_block( $block ) {
global $post;
/**
* Allows render_block() to be shortcircuited, by returning a non-null value.
* Allows render_block() to be short-circuited, by returning a non-null value.
*
* @since 5.1.0
*

8
wp-includes/canonical.php
View File

@ -849,13 +849,13 @@ function redirect_guess_404_permalink() {
/**
* Filters whether to attempt to guess a redirect URL for a 404 request.
*
* Passing a false value to the filter will disable the URL guessing
* Returning a false value from the filter will disable the URL guessing
* and return early without performing a redirect.
*
* @since 5.5.0
*
* @param bool $do_redirect_guess Whether to attempt to guess a redirect URL
* for a 404 request. Default is true.
* for a 404 request. Default true.
*/
if ( false === apply_filters( 'do_redirect_guess_404_permalink', true ) ) {
return false;
@ -864,7 +864,7 @@ function redirect_guess_404_permalink() {
/**
* Short-circuits the redirect URL guessing for 404 requests.
*
* Passing a non-null value to the filter will effectively short-circuit
* Returning a non-null value from the filter will effectively short-circuit
* the URL guessing, returning the passed value instead.
*
* @since 5.5.0
@ -881,7 +881,7 @@ function redirect_guess_404_permalink() {
/**
* Filters whether to perform a strict guess for a 404 redirect.
*
* Passing a truthy value to the filter will redirect only exact post_name matches.
* Returning a truthy value from the filter will redirect only exact post_name matches.
*
* @since 5.5.0
*

4
wp-includes/class-wp-oembed.php
View File

@ -381,8 +381,8 @@ class WP_oEmbed {
* This allows one to short-circuit the default logic, perhaps by
* replacing it with a routine that is more optimal for your setup.
*
* Passing a non-null value to the filter will effectively short-circuit retrieval,
* returning the passed value instead.
* Returning a non-null value from the filter will effectively short-circuit retrieval
* and return the passed value instead.
*
* @since 4.5.3
*

2
wp-includes/comment.php
View File

@ -831,7 +831,7 @@ function wp_allow_comment( $commentdata, $avoid_die = false ) {
* Filters a comment's approval status before it is set.
*
* @since 2.1.0
* @since 4.9.0 Returning a WP_Error value from the filter will shortcircuit comment insertion
* @since 4.9.0 Returning a WP_Error value from the filter will short-circuit comment insertion
* and allow skipping further processing.
*
* @param int|string|WP_Error $approved The approval status. Accepts 1, 0, 'spam', 'trash',

4
wp-includes/formatting.php
View File

@ -64,8 +64,8 @@ function wptexturize( $text, $reset = false ) {
/**
* Filters whether to skip running wptexturize().
*
* Passing false to the filter will effectively short-circuit wptexturize().
* returning the original text passed to the function instead.
* Returning false from the filter will effectively short-circuit wptexturize()
* and return the original text passed to the function instead.
*
* The filter runs only once, the first time wptexturize() is called.
*

12
wp-includes/functions.php
View File

@ -2654,8 +2654,8 @@ function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {
/**
* Filters whether to treat the upload bits as an error.
*
* Returning a non-array from the filter will effectively short-circuit preparing the upload
* bits, returning that value instead. An error message should be returned as a string.
* Returning a non-array from the filter will effectively short-circuit preparing the upload bits
* and return that value instead. An error message should be returned as a string.
*
* @since 3.0.0
*
@ -4578,7 +4578,7 @@ function wp_maybe_load_widgets() {
/**
* Filters whether to load the Widgets library.
*
* Passing a falsey value to the filter will effectively short-circuit
* Returning a falsey value from the filter will effectively short-circuit
* the Widgets library from loading.
*
* @since 2.8.0
@ -5580,8 +5580,8 @@ function global_terms_enabled() {
/**
* Filters whether global terms are enabled.
*
* Passing a non-null value to the filter will effectively short-circuit the function,
* returning the value of the 'global_terms_enabled' site option instead.
* Returning a non-null value from the filter will effectively short-circuit the function
* and return the value of the 'global_terms_enabled' site option instead.
*
* @since 3.0.0
*
@ -6448,7 +6448,7 @@ function wp_auth_check_load() {
/**
* Filters whether to load the authentication check.
*
* Passing a falsey value to the filter will effectively short-circuit
* Returning a falsey value from the filter will effectively short-circuit
* loading the authentication check.
*
* @since 3.6.0

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

@ -3857,8 +3857,8 @@ function wp_get_shortlink( $id = 0, $context = 'post', $allow_slugs = true ) {
/**
* Filters whether to preempt generating a shortlink for the given post.
*
* Passing a truthy value to the filter will effectively short-circuit the
* shortlink-generation process, returning that value instead.
* Returning a truthy value from the filter will effectively short-circuit
* the shortlink generation process, returning that value instead.
*
* @since 3.0.0
*

7
wp-includes/media.php
View File

@ -541,7 +541,7 @@ function image_resize_dimensions( $orig_w, $orig_h, $dest_w, $dest_h, $crop = fa
/**
* Filters whether to preempt calculating the image resize dimensions.
*
* Passing a non-null value to the filter will effectively short-circuit
* Returning a non-null value from the filter will effectively short-circuit
* image_resize_dimensions(), returning that value instead.
*
* @since 3.4.0
@ -1625,7 +1625,8 @@ function wp_lazy_loading_enabled( $tag_name, $context ) {
* @see wp_img_tag_add_srcset_and_sizes_attr()
*
* @param string $content The HTML content to be filtered.
* @param string $context Optional. Additional context to pass to the filters. Defaults to `current_filter()` when not set.
* @param string $context Optional. Additional context to pass to the filters.
* Defaults to `current_filter()` when not set.
* @return string Converted content with images modified.
*/
function wp_filter_content_tags( $content, $context = null ) {
@ -2369,7 +2370,7 @@ function wp_playlist_shortcode( $attr ) {
/**
* Filters the playlist output.
*
* Passing a non-empty value to the filter will short-circuit generation
* Returning a non-empty value from the filter will short-circuit generation
* of the default playlist output, returning the passed value instead.
*
* @since 3.9.0

5
wp-includes/nav-menu-template.php
View File

@ -89,9 +89,8 @@ function wp_nav_menu( $args = array() ) {
/**
* Filters whether to short-circuit the wp_nav_menu() output.
*
* Passing a non-null value to the filter will short-circuit
* wp_nav_menu(), echoing that value if $args->echo is true,
* returning that value otherwise.
* Returning a non-null value from the filter will short-circuit wp_nav_menu(),
* echoing that value if $args->echo is true, returning that value otherwise.
*
* @since 3.9.0
*

12
wp-includes/option.php
View File

@ -40,7 +40,7 @@ function get_option( $option, $default = false ) {
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
* Passing a truthy value to the filter will short-circuit retrieving
* Returning a truthy value from the filter will short-circuit retrieving
* the option value, returning the passed value instead.
*
* @since 1.5.0
@ -687,7 +687,7 @@ function get_transient( $transient ) {
*
* The dynamic portion of the hook name, `$transient`, refers to the transient name.
*
* Passing a truthy value to the filter will effectively short-circuit retrieval
* Returning a truthy value from the filter will effectively short-circuit retrieval
* of the transient, returning the passed value instead.
*
* @since 2.8.0
@ -1237,8 +1237,8 @@ function get_network_option( $network_id, $option, $default = false ) {
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
* Passing a truthy value to the filter will effectively short-circuit retrieval,
* returning the passed value instead.
* Returning a truthy value from the filter will effectively short-circuit retrieval
* and return the passed value instead.
*
* @since 2.9.0 As 'pre_site_option_' . $key
* @since 3.0.0
@ -1750,8 +1750,8 @@ function get_site_transient( $transient ) {
*
* The dynamic portion of the hook name, `$transient`, refers to the transient name.
*
* Passing a truthy value to the filter will effectively short-circuit retrieval,
* returning the passed value instead.
* Returning a truthy value from the filter will effectively short-circuit retrieval
* and return the passed value instead.
*
* @since 2.9.0
* @since 4.4.0 The `$transient` parameter was added.

4
wp-includes/post.php
View File

@ -3685,8 +3685,8 @@ function wp_insert_post( $postarr, $wp_error = false ) {
* 1. The post type supports the title, editor, and excerpt fields
* 2. The title, editor, and excerpt fields are all empty
*
* Passing a truthy value to the filter will effectively short-circuit
* the new post being inserted, returning 0. If $wp_error is true, a WP_Error
* Returning a truthy value from the filter will effectively short-circuit
* the new post being inserted and return 0. If $wp_error is true, a WP_Error
* will be returned instead.
*
* @since 3.3.0

4
wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php
View File

@ -682,11 +682,11 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
* Filters a comment before it is inserted via the REST API.
*
* Allows modification of the comment right before it is inserted via wp_insert_comment().
* Returning a WP_Error value from the filter will shortcircuit insertion and allow
* Returning a WP_Error value from the filter will short-circuit insertion and allow
* skipping further processing.
*
* @since 4.7.0
* @since 4.8.0 `$prepared_comment` can now be a WP_Error to shortcircuit insertion.
* @since 4.8.0 `$prepared_comment` can now be a WP_Error to short-circuit insertion.
*
* @param array|WP_Error $prepared_comment The prepared comment data for wp_insert_comment().
* @param WP_REST_Request $request Request used to insert the comment.

2
wp-includes/user.php
View File

@ -608,7 +608,7 @@ function get_blogs_of_user( $user_id, $all = false ) {
/**
* Filters the list of a user's sites before it is populated.
*
* Passing a non-null value to the filter will effectively short circuit
* Returning a non-null value from the filter will effectively short circuit
* get_blogs_of_user(), returning that value instead.
*
* @since 4.6.0

2
wp-includes/version.php
View File

@ -13,7 +13,7 @@
*
* @global string $wp_version
*/
$wp_version = '5.5-alpha-48184';
$wp_version = '5.5-alpha-48185';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.