From 40c389c95e2ae36b6f0bd52eac54a28edf0149d3 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov.ru@gmail.com>
Date: Fri, 26 Jun 2020 18:49:09 +0000
Subject: [PATCH] Docs: Standardize on "Returning a value from the filter" vs.
 "Passing a value to the filter".

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
---
 wp-admin/includes/export.php                         |  6 +++---
 wp-admin/includes/file.php                           |  4 ++--
 wp-admin/includes/media.php                          |  2 +-
 wp-admin/includes/misc.php                           |  4 ++--
 wp-includes/blocks.php                               |  2 +-
 wp-includes/canonical.php                            |  8 ++++----
 wp-includes/class-wp-oembed.php                      |  4 ++--
 wp-includes/comment.php                              |  2 +-
 wp-includes/formatting.php                           |  4 ++--
 wp-includes/functions.php                            | 12 ++++++------
 wp-includes/link-template.php                        |  4 ++--
 wp-includes/media.php                                |  7 ++++---
 wp-includes/nav-menu-template.php                    |  5 ++---
 wp-includes/option.php                               | 12 ++++++------
 wp-includes/post.php                                 |  4 ++--
 .../endpoints/class-wp-rest-comments-controller.php  |  4 ++--
 wp-includes/user.php                                 |  2 +-
 wp-includes/version.php                              |  2 +-
 18 files changed, 44 insertions(+), 44 deletions(-)

diff --git a/wp-admin/includes/export.php b/wp-admin/includes/export.php
index 315785738d..7b1b797eb4 100644
--- a/wp-admin/includes/export.php
+++ b/wp-admin/includes/export.php
@@ -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
diff --git a/wp-admin/includes/file.php b/wp-admin/includes/file.php
index c879acba44..af7def5aae 100644
--- a/wp-admin/includes/file.php
+++ b/wp-admin/includes/file.php
@@ -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
 	 *
diff --git a/wp-admin/includes/media.php b/wp-admin/includes/media.php
index 422d015b5e..79fb8c2f0d 100644
--- a/wp-admin/includes/media.php
+++ b/wp-admin/includes/media.php
@@ -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', '' ) ) {
diff --git a/wp-admin/includes/misc.php b/wp-admin/includes/misc.php
index d2103f45b7..dfa7af10b9 100644
--- a/wp-admin/includes/misc.php
+++ b/wp-admin/includes/misc.php
@@ -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
 				 *
diff --git a/wp-includes/blocks.php b/wp-includes/blocks.php
index 0a34af25f6..9b612d68bd 100644
--- a/wp-includes/blocks.php
+++ b/wp-includes/blocks.php
@@ -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
 	 *
diff --git a/wp-includes/canonical.php b/wp-includes/canonical.php
index 8e1c46d781..aa59766947 100644
--- a/wp-includes/canonical.php
+++ b/wp-includes/canonical.php
@@ -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
 		 *
diff --git a/wp-includes/class-wp-oembed.php b/wp-includes/class-wp-oembed.php
index 18d38ee757..9a073a3955 100644
--- a/wp-includes/class-wp-oembed.php
+++ b/wp-includes/class-wp-oembed.php
@@ -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
 		 *
diff --git a/wp-includes/comment.php b/wp-includes/comment.php
index 880578d198..ca1f77b560 100644
--- a/wp-includes/comment.php
+++ b/wp-includes/comment.php
@@ -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',
diff --git a/wp-includes/formatting.php b/wp-includes/formatting.php
index 6b15beac67..285134f21f 100644
--- a/wp-includes/formatting.php
+++ b/wp-includes/formatting.php
@@ -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.
 		 *
diff --git a/wp-includes/functions.php b/wp-includes/functions.php
index b71512b803..09a5c17ff3 100644
--- a/wp-includes/functions.php
+++ b/wp-includes/functions.php
@@ -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
diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php
index ec586af168..234861a2cc 100644
--- a/wp-includes/link-template.php
+++ b/wp-includes/link-template.php
@@ -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
 	 *
diff --git a/wp-includes/media.php b/wp-includes/media.php
index 720f91db2b..f6eeb829c0 100644
--- a/wp-includes/media.php
+++ b/wp-includes/media.php
@@ -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
diff --git a/wp-includes/nav-menu-template.php b/wp-includes/nav-menu-template.php
index ffe9777cb2..a6a99cbad8 100644
--- a/wp-includes/nav-menu-template.php
+++ b/wp-includes/nav-menu-template.php
@@ -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
 	 *
diff --git a/wp-includes/option.php b/wp-includes/option.php
index b1d553bf7a..c30033d602 100644
--- a/wp-includes/option.php
+++ b/wp-includes/option.php
@@ -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.
diff --git a/wp-includes/post.php b/wp-includes/post.php
index c123ff47ac..e196d09726 100644
--- a/wp-includes/post.php
+++ b/wp-includes/post.php
@@ -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
diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php
index c3f2f35b8d..97dbb737c7 100644
--- a/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php
+++ b/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php
@@ -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.
diff --git a/wp-includes/user.php b/wp-includes/user.php
index 15ea259292..6d75e07c1e 100644
--- a/wp-includes/user.php
+++ b/wp-includes/user.php
@@ -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
diff --git a/wp-includes/version.php b/wp-includes/version.php
index d1a24eb1a2..e3a7440b38 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -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.