Docs: Apply inline `@see` tags to hooks referenced in DocBlocks for core classes.

Applying these specially-crafted `@see` tags allows the Code Reference parser to recognize and link these elements as actions and filters.

See #36921.

Built from https://develop.svn.wordpress.org/trunk@37539


git-svn-id: http://core.svn.wordpress.org/trunk@37507 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/class-wp-comment-query.php

@@ -62,7 +62,7 @@ class WP_Comment_Query {
 	/**
 	 * SQL WHERE clause.
 	 *
-	 * Stored after the 'comments_clauses' filter is run on the compiled WHERE sub-clauses.
+	 * Stored after the {@see 'comments_clauses'} filter is run on the compiled WHERE sub-clauses.
 	 *
 	 * @since 4.4.2
 	 * @access protected

wp-includes/class-wp-customize-manager.php

@@ -905,8 +905,8 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param mixed $return Value passed through for wp_die_handler filter.
-	 * @return mixed Value passed through for wp_die_handler filter.
+	 * @param mixed $return Value passed through for {@see 'wp_die_handler'} filter.
+	 * @return mixed Value passed through for {@see 'wp_die_handler'} filter.
 	 */
 	public function remove_preview_signature( $return = null ) {
 		remove_action( 'shutdown', array( $this, 'customize_preview_signature' ), 1000 );

wp-includes/class-wp-customize-widgets.php

@@ -349,7 +349,7 @@ final class WP_Customize_Widgets {
 	/**
 	 * Ensures widgets are available for all types of previews.
 	 *
-	 * When in preview, hook to 'customize_register' for settings after WordPress is loaded
+	 * When in preview, hook to {@see 'customize_register'} for settings after WordPress is loaded
 	 * so that all filters have been initialized (e.g. Widget Visibility).
 	 *
 	 * @since 3.9.0
@@ -556,7 +556,7 @@ final class WP_Customize_Widgets {
 	 * have widths of 400 and yet they still render fine in the Customizer panel.
 	 *
 	 * This method will return all Core widgets as being not wide, but this can be
-	 * overridden with the is_wide_widget_in_customizer filter.
+	 * overridden with the {@see 'is_wide_widget_in_customizer'} filter.
 	 *
 	 * @since 3.9.0
 	 * @access public
@@ -1989,32 +1989,48 @@ final class WP_Customize_Widgets {
 	}
 
 	/**
+	 * {@internal Missing Summary}
+	 *
+	 * See the {@see 'customize_dynamic_setting_args'} filter.
+	 *
 	 * @since 3.9.0
-	 * @deprecated 4.2.0 Deprecated in favor of customize_dynamic_setting_args filter.
+	 * @deprecated 4.2.0 Deprecated in favor of the {@see 'customize_dynamic_setting_args'} filter.
 	 */
 	public function setup_widget_addition_previews() {
 		_deprecated_function( __METHOD__, '4.2.0' );
 	}
 
 	/**
+	 * {@internal Missing Summary}
+	 *
+	 * See the {@see 'customize_dynamic_setting_args'} filter.
+	 *
 	 * @since 3.9.0
-	 * @deprecated 4.2.0 Deprecated in favor of customize_dynamic_setting_args filter.
+	 * @deprecated 4.2.0 Deprecated in favor of the {@see 'customize_dynamic_setting_args'} filter.
 	 */
 	public function prepreview_added_sidebars_widgets() {
 		_deprecated_function( __METHOD__, '4.2.0' );
 	}
 
 	/**
+	 * {@internal Missing Summary}
+	 *
+	 * See the {@see 'customize_dynamic_setting_args'} filter.
+	 *
 	 * @since 3.9.0
-	 * @deprecated 4.2.0 Deprecated in favor of customize_dynamic_setting_args filter.
+	 * @deprecated 4.2.0 Deprecated in favor of the {@see 'customize_dynamic_setting_args'} filter.
 	 */
 	public function prepreview_added_widget_instance() {
 		_deprecated_function( __METHOD__, '4.2.0' );
 	}
 
 	/**
+	 * {@internal Missing Summary}
+	 *
+	 * See the {@see 'customize_dynamic_setting_args'} filter.
+	 *
 	 * @since 3.9.0
-	 * @deprecated 4.2.0 Deprecated in favor of customize_dynamic_setting_args filter.
+	 * @deprecated 4.2.0 Deprecated in favor of the {@see 'customize_dynamic_setting_args'} filter.
 	 */
 	public function remove_prepreview_filters() {
 		_deprecated_function( __METHOD__, '4.2.0' );

wp-includes/class-wp-embed.php

@@ -16,7 +16,12 @@ class WP_Embed {
 
 	/**
 	 * When a URL cannot be embedded, return false instead of returning a link
-	 * or the URL. Bypasses the 'embed_maybe_make_link' filter.
+	 * or the URL.
+	 *
+	 * Bypasses the {@see 'embed_maybe_make_link'} filter.
+	 *
+	 * @access public
+	 * @var bool
 	 */
 	public $return_false_on_fail = false;
 

wp-includes/class-wp-metadata-lazyloader.php

@@ -160,7 +160,7 @@ class WP_Metadata_Lazyloader {
 	 *
 	 * @since 4.5.0
 	 *
-	 * @param mixed $check The `$check` param passed from the 'get_comment_metadata' hook.
+	 * @param mixed $check The `$check` param passed from the {@see 'get_comment_metadata'} hook.
 	 * @return mixed The original value of `$check`, so as not to short-circuit `get_comment_metadata()`.
 	 */
 	public function lazyload_comment_meta( $check ) {

wp-includes/class-wp-rewrite.php

@@ -1252,13 +1252,13 @@ class WP_Rewrite {
 	/**
 	 * Constructs rewrite matches and queries from permalink structure.
 	 *
-	 * Runs the action 'generate_rewrite_rules' with the parameter that is an
+	 * Runs the action {@see 'generate_rewrite_rules'} with the parameter that is an
 	 * reference to the current WP_Rewrite instance to further manipulate the
-	 * permalink structures and rewrite rules. Runs the 'rewrite_rules_array'
+	 * permalink structures and rewrite rules. Runs the {@see 'rewrite_rules_array'}
 	 * filter on the full rewrite rule array.
 	 *
 	 * There are two ways to manipulate the rewrite rules, one by hooking into
-	 * the 'generate_rewrite_rules' action and gaining full control of the
+	 * the {@see 'generate_rewrite_rules'} action and gaining full control of the
 	 * object or just manipulating the rewrite rule array before it is passed
 	 * from the function.
 	 *
@@ -1872,7 +1872,7 @@ class WP_Rewrite {
 	 * between the current permalink structure and the parameter value. Calls
 	 * WP_Rewrite::init() after the option is updated.
 	 *
-	 * Fires the 'permalink_structure_changed' action once the init call has
+	 * Fires the {@see 'permalink_structure_changed'} action once the init call has
 	 * processed passing the old and new values
 	 *
 	 * @since 1.5.0

wp-includes/class-wp-theme.php

@@ -170,7 +170,7 @@ final class WP_Theme implements ArrayAccess {
 	/**
 	 * Flag for whether the themes cache bucket should be persistently cached.
 	 *
-	 * Default is false. Can be set with the wp_cache_themes_persistently filter.
+	 * Default is false. Can be set with the {@see 'wp_cache_themes_persistently'} filter.
 	 *
 	 * @static
 	 * @access private
@@ -920,7 +920,7 @@ final class WP_Theme implements ArrayAccess {
 	 *
 	 * This is typically the absolute URL to wp-content/themes. This forms the basis
 	 * for all other URLs returned by WP_Theme, so we pass it to the public function
-	 * get_theme_root_uri() and allow it to run the theme_root_uri filter.
+	 * get_theme_root_uri() and allow it to run the {@see 'theme_root_uri'} filter.
 	 *
 	 * @since 3.4.0
 	 * @access public

wp-includes/class-wp-xmlrpc-server.php

@@ -14,7 +14,7 @@
  * options, etc.
  *
  * As of WordPress 3.5.0, XML-RPC is enabled by default. It can be disabled
- * via the xmlrpc_enabled filter found in wp_xmlrpc_server::login().
+ * via the {@see 'xmlrpc_enabled'} filter found in wp_xmlrpc_server::login().
  *
  * @package WordPress
  * @subpackage Publishing
@@ -54,11 +54,11 @@ class wp_xmlrpc_server extends IXR_Server {
 	protected $auth_failed = false;
 
 	/**
-	 * Register all of the XMLRPC methods that XMLRPC server understands.
+	 * Registers all of the XMLRPC methods that XMLRPC server understands.
 	 *
 	 * Sets up server and method property. Passes XMLRPC
-	 * methods through the 'xmlrpc_methods' filter to allow plugins to extend
-	 * or replace XMLRPC methods.
+	 * methods through the {@see 'xmlrpc_methods'} filter to allow plugins to extend
+	 * or replace XML-RPC methods.
 	 *
 	 * @since 1.5.0
 	 */

wp-includes/customize/class-wp-customize-nav-menu-item-setting.php

@@ -132,6 +132,8 @@ class WP_Customize_Nav_Menu_Item_Setting extends WP_Customize_Setting {
 	/**
 	 * Status for calling the update method, used in customize_save_response filter.
 	 *
+	 * See {@see 'customize_save_response'}.
+	 *
 	 * When status is inserted, the placeholder post ID is stored in $previous_post_id.
 	 * When status is error, the error is stored in $update_error.
 	 *
@@ -658,11 +660,11 @@ class WP_Customize_Nav_Menu_Item_Setting extends WP_Customize_Setting {
 	}
 
 	/**
-	 * Create/update the nav_menu_item post for this setting.
+	 * Creates/updates the nav_menu_item post for this setting.
 	 *
 	 * Any created menu items will have their assigned post IDs exported to the client
-	 * via the customize_save_response filter. Likewise, any errors will be exported
-	 * to the client via the customize_save_response() filter.
+	 * via the {@see 'customize_save_response'} filter. Likewise, any errors will be
+	 * exported to the client via the customize_save_response() filter.
 	 *
 	 * To delete a menu, the client can send false as the value.
 	 *

wp-includes/customize/class-wp-customize-nav-menu-setting.php

@@ -74,7 +74,7 @@ class WP_Customize_Nav_Menu_Setting extends WP_Customize_Setting {
 	/**
 	 * Previous (placeholder) term ID used before creating a new menu.
 	 *
-	 * This value will be exported to JS via the customize_save_response filter
+	 * This value will be exported to JS via the {@see 'customize_save_response'} filter
 	 * so that JavaScript can update the settings to refer to the newly-assigned
 	 * term ID. This value is always negative to indicate it does not refer to
 	 * a real term.
@@ -100,8 +100,10 @@ class WP_Customize_Nav_Menu_Setting extends WP_Customize_Setting {
 	/**
 	 * Status for calling the update method, used in customize_save_response filter.
 	 *
-	 * When status is inserted, the placeholder term ID is stored in $previous_term_id.
-	 * When status is error, the error is stored in $update_error.
+	 * See {@see 'customize_save_response'}.
+	 *
+	 * When status is inserted, the placeholder term ID is stored in `$previous_term_id`.
+	 * When status is error, the error is stored in `$update_error`.
 	 *
 	 * @since 4.3.0
 	 * @access public
@@ -447,6 +449,8 @@ class WP_Customize_Nav_Menu_Setting extends WP_Customize_Setting {
 	/**
 	 * Storage for data to be sent back to client in customize_save_response filter.
 	 *
+	 * See {@see 'customize_save_response'}.
+	 *
 	 * @access protected
 	 * @since 4.3.0
 	 * @var array
@@ -459,7 +463,7 @@ class WP_Customize_Nav_Menu_Setting extends WP_Customize_Setting {
 	 * Create/update the nav_menu term for this setting.
 	 *
 	 * Any created menus will have their assigned term IDs exported to the client
-	 * via the customize_save_response filter. Likewise, any errors will be exported
+	 * via the {@see 'customize_save_response'} filter. Likewise, any errors will be exported
 	 * to the client via the customize_save_response() filter.
 	 *
 	 * To delete a menu, the client can send false as the value.

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.6-alpha-37538';
+$wp_version = '4.6-alpha-37539';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.