From 9193013158d02ecd51ab8aa52d594aa789ac9836 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Mon, 23 May 2016 19:02:28 +0000 Subject: [PATCH] Docs: Apply inline `@see` tags to hooks referenced in DocBlocks in a variety of wp-includes/* files. Applying these specially-crafted `@see` tags allows the Code Reference parser to recognize and link these elements as actions and filters. Fixes #36921. Built from https://develop.svn.wordpress.org/trunk@37544 git-svn-id: http://core.svn.wordpress.org/trunk@37512 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/nav-menu-template.php | 4 ++-- wp-includes/option.php | 4 ++-- wp-includes/pluggable.php | 4 ++-- wp-includes/post-template.php | 8 +++++--- wp-includes/post.php | 8 +++++--- wp-includes/query.php | 4 ++-- wp-includes/rest-api.php | 2 +- wp-includes/revision.php | 2 +- wp-includes/rewrite.php | 2 +- wp-includes/session.php | 2 +- wp-includes/taxonomy.php | 4 ++-- wp-includes/theme.php | 15 +++++++++------ wp-includes/user.php | 6 ++++-- wp-includes/version.php | 2 +- wp-includes/widgets.php | 15 +++++++-------- wp-includes/wp-db.php | 4 ++-- wp-includes/wp-diff.php | 2 +- 17 files changed, 48 insertions(+), 40 deletions(-) diff --git a/wp-includes/nav-menu-template.php b/wp-includes/nav-menu-template.php index f22cb9eed7..aaba786f41 100644 --- a/wp-includes/nav-menu-template.php +++ b/wp-includes/nav-menu-template.php @@ -66,12 +66,12 @@ class Walker_Nav_Menu extends Walker { } /** - * Start the element output. + * Starts the element output. * * @see Walker::start_el() * * @since 3.0.0 - * @since 4.4.0 'nav_menu_item_args' filter was added. + * @since 4.4.0 The {@see 'nav_menu_item_args'} filter was added. * * @param string $output Passed by reference. Used to append additional content. * @param object $item Menu item data object. diff --git a/wp-includes/option.php b/wp-includes/option.php index 566ac2e756..3bccd29d84 100644 --- a/wp-includes/option.php +++ b/wp-includes/option.php @@ -16,8 +16,8 @@ * * If the option was serialized then it will be unserialized when it is returned. * - * Any scalar values will be returned as strings. You may coerce the return type of a given option by registering a - * 'option_{$option}' filter callback. + * Any scalar values will be returned as strings. You may coerce the return type of + * a given option by registering an {@see 'option_$option'} filter callback. * * @since 1.5.0 * diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php index da3f83854f..4668c2cb1a 100644 --- a/wp-includes/pluggable.php +++ b/wp-includes/pluggable.php @@ -154,10 +154,10 @@ if ( !function_exists( 'wp_mail' ) ) : * * The default content type is 'text/plain' which does not allow using HTML. * However, you can set the content type of the email by using the - * 'wp_mail_content_type' filter. + * {@see 'wp_mail_content_type'} filter. * * The default charset is based on the charset used on the blog. The charset can - * be set using the 'wp_mail_charset' filter. + * be set using the {@see 'wp_mail_charset'} filter. * * @since 1.2.1 * diff --git a/wp-includes/post-template.php b/wp-includes/post-template.php index fa21c86aeb..7cfb9ac798 100644 --- a/wp-includes/post-template.php +++ b/wp-includes/post-template.php @@ -415,15 +415,17 @@ function post_class( $class = '', $post_id = null ) { } /** - * Retrieve the classes for the post div as an array. + * Retrieves the classes for the post div as an array. * * The class names are many. If the post is a sticky, then the 'sticky' * class name. The class 'hentry' is always added to each post. If the post has a * post thumbnail, 'has-post-thumbnail' is added as a class. For each taxonomy that * the post belongs to, a class will be added of the format '{$taxonomy}-{$slug}' - - * eg 'category-foo' or 'my_custom_taxonomy-bar'. The 'post_tag' taxonomy is a special + * eg 'category-foo' or 'my_custom_taxonomy-bar'. + * + * The 'post_tag' taxonomy is a special * case; the class has the 'tag-' prefix instead of 'post_tag-'. All classes are - * passed through the filter, 'post_class' with the list of classes, followed by + * passed through the filter, {@see 'post_class'}, with the list of classes, followed by * $class parameter value, with the post ID as the last parameter. * * @since 2.7.0 diff --git a/wp-includes/post.php b/wp-includes/post.php index b786f83cd3..4ce2ac19e5 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -13,6 +13,8 @@ /** * Creates the initial post types when 'init' action is fired. * + * See {@see 'init'}. + * * @since 2.9.0 */ function create_initial_post_types() { @@ -3958,8 +3960,8 @@ function wp_set_post_categories( $post_ID = 0, $post_categories = array(), $appe * When a post is saved, the post status is "transitioned" from one status to another, * though this does not always mean the status has actually changed before and after * the save. This function fires a number of action hooks related to that transition: - * the generic 'transition_post_status' action, as well as the dynamic hooks - * `"{$old_status}_to_{$new_status}"` and `"{$new_status}_{$post->post_type}"`. Note + * the generic {@see 'transition_post_status'} action, as well as the dynamic hooks + * {@see '$old_status_to_$new_status'} and {@see '$new_status_$post->post_type'}. Note * that the function does not transition the post object in the database. * * For instance: When publishing a post for the first time, the post status may transition @@ -5926,7 +5928,7 @@ function wp_get_post_parent_id( $post_ID ) { * Check the given subset of the post hierarchy for hierarchy loops. * * Prevents loops from forming and breaks those that it finds. Attached - * to the 'wp_insert_post_parent' filter. + * to the {@see 'wp_insert_post_parent'} filter. * * @since 3.1.0 * diff --git a/wp-includes/query.php b/wp-includes/query.php index b609ce798a..b0df07b0ee 100644 --- a/wp-includes/query.php +++ b/wp-includes/query.php @@ -3883,9 +3883,9 @@ class WP_Query { } /** - * Whether there are more posts available in the loop. + * Determines whether there are more posts available in the loop. * - * Calls action 'loop_end', when the loop is complete. + * Calls the {@see 'loop_end'} action when the loop is complete. * * @since 1.5.0 * @access public diff --git a/wp-includes/rest-api.php b/wp-includes/rest-api.php index 174b24f1aa..ebcf6a91f5 100644 --- a/wp-includes/rest-api.php +++ b/wp-includes/rest-api.php @@ -208,7 +208,7 @@ function get_rest_url( $blog_id = null, $path = '/', $scheme = 'rest' ) { /** * Filters the REST URL. * - * Use this filter to adjust the url returned by the `get_rest_url` function. + * Use this filter to adjust the url returned by the get_rest_url() function. * * @since 4.4.0 * diff --git a/wp-includes/revision.php b/wp-includes/revision.php index 66ebe1b15a..da16d174dd 100644 --- a/wp-includes/revision.php +++ b/wp-includes/revision.php @@ -322,7 +322,7 @@ function _wp_put_post_revision( $post = null, $autosave = false ) { * * @param int|WP_Post $post The post ID or object. * @param string $output Optional. OBJECT, ARRAY_A, or ARRAY_N. - * @param string $filter Optional sanitation filter. @see sanitize_post(). + * @param string $filter Optional sanitation filter. See sanitize_post(). * @return WP_Post|array|null Null if error or post object if success. */ function wp_get_post_revision(&$post, $output = OBJECT, $filter = 'raw') { diff --git a/wp-includes/rewrite.php b/wp-includes/rewrite.php index f47a8123b1..705e5f2bc8 100644 --- a/wp-includes/rewrite.php +++ b/wp-includes/rewrite.php @@ -144,7 +144,7 @@ function add_rewrite_rule( $regex, $query, $after = 'bottom' ) { * Add a new rewrite tag (like %postname%). * * The $query parameter is optional. If it is omitted you must ensure that - * you call this on, or before, the 'init' hook. This is because $query defaults + * you call this on, or before, the {@see 'init'} hook. This is because $query defaults * to "$tag=", and for this to work a new query var has to be added. * * @since 2.1.0 diff --git a/wp-includes/session.php b/wp-includes/session.php index 7137159329..63ab8fe589 100644 --- a/wp-includes/session.php +++ b/wp-includes/session.php @@ -108,7 +108,7 @@ abstract class WP_Session_Tokens { * * This function generates a token and stores it with the associated * expiration time (and potentially other session information via the - * `attach_session_information` filter). + * {@see 'attach_session_information'} filter). * * @since 4.0.0 * @access public diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index f2a0169852..a60052c2da 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -1233,7 +1233,7 @@ function get_terms( $args = array(), $deprecated = '' ) { /** * Filters the terms query default arguments. * - * Use 'get_terms_args' to filter the passed arguments. + * Use {@see 'get_terms_args'} to filter the passed arguments. * * @since 4.4.0 * @@ -2107,7 +2107,7 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) { /** * Filters the category nicename before it is sanitized. * - * Use the pre_{$taxonomy}_{$field} hook instead. + * Use the {@see 'pre_$taxonomy_$field'} hook instead. * * @since 2.0.3 * diff --git a/wp-includes/theme.php b/wp-includes/theme.php index ee40ba1820..0526fe8f65 100644 --- a/wp-includes/theme.php +++ b/wp-includes/theme.php @@ -233,7 +233,7 @@ function get_stylesheet_uri() { } /** - * Retrieve localized stylesheet URI. + * Retrieves the localized stylesheet URI. * * The stylesheet directory for the localized stylesheet files are located, by * default, in the base theme directory. The name of the locale file will be the @@ -241,7 +241,8 @@ function get_stylesheet_uri() { * stylesheet will be checked for existence, for example 'ltr.css'. * * The theme may change the location of the stylesheet directory by either using - * the 'stylesheet_directory_uri' filter or the 'locale_stylesheet_uri' filter. + * the {@see 'stylesheet_directory_uri'} or {@see 'locale_stylesheet_uri'} filters. + * * If you want to change the location of the stylesheet files for the entire * WordPress workflow, then change the former. If you just have the locale in a * separate folder, then change the latter. @@ -760,7 +761,7 @@ function switch_theme( $stylesheet ) { * But if it doesn't exist, it'll fall back to the latest core default theme that does exist. * Will switch theme to the fallback theme if current theme does not validate. * - * You can use the 'validate_current_theme' filter to return false to + * You can use the {@see 'validate_current_theme'} filter to return false to * disable this functionality. * * @since 1.5.0 @@ -1516,8 +1517,8 @@ function get_editor_stylesheets() { * Allows a theme to register its support of a certain feature * * Must be called in the theme's functions.php file to work. - * If attached to a hook, it must be after_setup_theme. - * The init hook may be too late for some features. + * If attached to a hook, it must be {@see 'after_setup_theme'}. + * The {@see 'init'} hook may be too late for some features. * * @since 2.9.0 * @@ -2013,7 +2014,9 @@ function _delete_attachment_theme_mod( $id ) { } /** - * Checks if a theme has been changed and runs 'after_switch_theme' hook on the next WP load + * Checks if a theme has been changed and runs 'after_switch_theme' hook on the next WP load. + * + * See {@see 'after_switch_theme'}. * * @since 3.3.0 */ diff --git a/wp-includes/user.php b/wp-includes/user.php index 26e4a1149f..aa225a6718 100644 --- a/wp-includes/user.php +++ b/wp-includes/user.php @@ -311,12 +311,12 @@ function wp_authenticate_spam_check( $user ) { } /** - * Validate the logged-in cookie. + * Validates the logged-in cookie. * * Checks the logged-in cookie if the previous auth cookie could not be * validated and parsed. * - * This is a callback for the determine_current_user filter, rather than API. + * This is a callback for the {@see 'determine_current_user'} filter, rather than API. * * @since 3.9.0 * @@ -2039,6 +2039,8 @@ function get_password_reset_key( $user ) { /** * Fires before a new password is retrieved. * + * Use the {@see 'retrieve_password'} hook instead. + * * @since 1.5.0 * @deprecated 1.5.1 Misspelled. Use 'retrieve_password' hook instead. * diff --git a/wp-includes/version.php b/wp-includes/version.php index de62b75372..ef18ca026c 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @global string $wp_version */ -$wp_version = '4.6-alpha-37543'; +$wp_version = '4.6-alpha-37544'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. diff --git a/wp-includes/widgets.php b/wp-includes/widgets.php index e67f59f3c1..3540be9b30 100644 --- a/wp-includes/widgets.php +++ b/wp-includes/widgets.php @@ -114,10 +114,10 @@ function register_widget($widget_class) { } /** - * Unregister a widget + * Unregisters a widget. * - * Unregisters a WP_Widget widget. Useful for unregistering default widgets. - * Run within a function hooked to the widgets_init action. + * Unregisters a WP_Widget widget. Useful for un-registering default widgets. + * Run within a function hooked to the {@see 'widgets_init'} action. * * @since 2.8.0 * @@ -125,7 +125,7 @@ function register_widget($widget_class) { * * @global WP_Widget_Factory $wp_widget_factory * - * @param string $widget_class The name of a class that extends WP_Widget + * @param string $widget_class The name of a class that extends WP_Widget. */ function unregister_widget($widget_class) { global $wp_widget_factory; @@ -780,7 +780,7 @@ function dynamic_sidebar( $index = 1 ) { * the widget with that callback/$id_base AND that ID is found. * * NOTE: $widget_id and $id_base are the same for single widgets. To be effective - * this function has to run after widgets have initialized, at action 'init' or later. + * this function has to run after widgets have initialized, at action {@see 'init'} or later. * * @since 2.2.0 * @@ -1429,10 +1429,9 @@ function wp_widget_rss_process( $widget_rss, $check_feed = true ) { } /** - * Register all of the default WordPress widgets on startup. + * Registers all of the default WordPress widgets on startup. * - * Calls 'widgets_init' action after all of the WordPress widgets have been - * registered. + * Calls {@see 'widgets_init'} action after all of the WordPress widgets have been registered. * * @since 2.2.0 */ diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php index 49b6a9ddb8..cffa68452e 100644 --- a/wp-includes/wp-db.php +++ b/wp-includes/wp-db.php @@ -1584,10 +1584,10 @@ class wpdb { } /** - * Check that the connection to the database is still up. If not, try to reconnect. + * Checks that the connection to the database is still up. If not, try to reconnect. * * If this function is unable to reconnect, it will forcibly die, or if after the - * the template_redirect hook has been fired, return false instead. + * the {@see 'template_redirect'} hook has been fired, return false instead. * * If $allow_bail is false, the lack of database connection will need * to be handled manually. diff --git a/wp-includes/wp-diff.php b/wp-includes/wp-diff.php index 1248cd66b7..8eeacddc15 100644 --- a/wp-includes/wp-diff.php +++ b/wp-includes/wp-diff.php @@ -159,7 +159,7 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer { $processed_line = htmlspecialchars( $line ); /** - * Contextually filter a diffed line. + * Contextually filters a diffed line. * * Filters TextDiff processing of diffed line. By default, diffs are processed with * htmlspecialchars. Use this filter to remove or change the processing. Passes a context