From b208dae5e66eb5c2382b1c49e74fe26cd88f7f68 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Mon, 23 May 2016 18:53:05 +0000 Subject: [PATCH] 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. git-svn-id: https://develop.svn.wordpress.org/trunk@37539 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/class-wp-comment-query.php | 2 +- .../class-wp-customize-manager.php | 4 +-- .../class-wp-customize-widgets.php | 28 +++++++++++++++---- src/wp-includes/class-wp-embed.php | 7 ++++- .../class-wp-metadata-lazyloader.php | 2 +- src/wp-includes/class-wp-rewrite.php | 8 +++--- src/wp-includes/class-wp-theme.php | 4 +-- src/wp-includes/class-wp-xmlrpc-server.php | 8 +++--- ...ass-wp-customize-nav-menu-item-setting.php | 8 ++++-- .../class-wp-customize-nav-menu-setting.php | 12 +++++--- 10 files changed, 55 insertions(+), 28 deletions(-) diff --git a/src/wp-includes/class-wp-comment-query.php b/src/wp-includes/class-wp-comment-query.php index 78763b74da..bccb7a9bbe 100644 --- a/src/wp-includes/class-wp-comment-query.php +++ b/src/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 diff --git a/src/wp-includes/class-wp-customize-manager.php b/src/wp-includes/class-wp-customize-manager.php index 67f25be481..f89887eb9e 100644 --- a/src/wp-includes/class-wp-customize-manager.php +++ b/src/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 ); diff --git a/src/wp-includes/class-wp-customize-widgets.php b/src/wp-includes/class-wp-customize-widgets.php index b02ad945e9..16549ff692 100644 --- a/src/wp-includes/class-wp-customize-widgets.php +++ b/src/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' ); diff --git a/src/wp-includes/class-wp-embed.php b/src/wp-includes/class-wp-embed.php index 4cb475f5d4..5f22e92a5c 100644 --- a/src/wp-includes/class-wp-embed.php +++ b/src/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; diff --git a/src/wp-includes/class-wp-metadata-lazyloader.php b/src/wp-includes/class-wp-metadata-lazyloader.php index 2af4fea0a1..beaf249f4e 100644 --- a/src/wp-includes/class-wp-metadata-lazyloader.php +++ b/src/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 ) { diff --git a/src/wp-includes/class-wp-rewrite.php b/src/wp-includes/class-wp-rewrite.php index adcbc0155a..2c5761566d 100644 --- a/src/wp-includes/class-wp-rewrite.php +++ b/src/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 diff --git a/src/wp-includes/class-wp-theme.php b/src/wp-includes/class-wp-theme.php index 489bd53712..fc1bf91a78 100644 --- a/src/wp-includes/class-wp-theme.php +++ b/src/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 diff --git a/src/wp-includes/class-wp-xmlrpc-server.php b/src/wp-includes/class-wp-xmlrpc-server.php index 45b368620f..40b836103b 100644 --- a/src/wp-includes/class-wp-xmlrpc-server.php +++ b/src/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 */ diff --git a/src/wp-includes/customize/class-wp-customize-nav-menu-item-setting.php b/src/wp-includes/customize/class-wp-customize-nav-menu-item-setting.php index 20c661a807..c71ab09754 100644 --- a/src/wp-includes/customize/class-wp-customize-nav-menu-item-setting.php +++ b/src/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. * diff --git a/src/wp-includes/customize/class-wp-customize-nav-menu-setting.php b/src/wp-includes/customize/class-wp-customize-nav-menu-setting.php index f62b5f460a..0275c79a01 100644 --- a/src/wp-includes/customize/class-wp-customize-nav-menu-setting.php +++ b/src/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.