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

@@ -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.

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
  *

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
  *

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

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
  *

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

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
 	 *

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') {

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

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

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
 			 *

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
  */

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.
 	 *

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.

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
  */

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.

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