Docs: Remove/replace invalid inline `@link` tags in DocBlocks in wp-includes/*.

Fixes #36910.

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


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

wp-includes/category-template.php

@@ -705,9 +705,8 @@ function wp_list_categories( $args = '' ) {
  * The 'post_type' argument is used only when 'link' is set to 'edit'. It determines the post_type
  * passed to edit.php for the popular tags edit links.
  *
- * The 'exclude' and 'include' arguments are used for the {@link get_tags()}
+ * The 'exclude' and 'include' arguments are used for the get_tags() function. Only one
- * function. Only one should be used, because only one will be used and the
+ * should be used, because only one will be used and the other ignored, if they are both set.
- * other ignored, if they are both set.
  *
  * @since 2.3.0
  *

wp-includes/class-wp-ajax-response.php

@@ -15,7 +15,7 @@ class WP_Ajax_Response {
 	public $responses = array();
 
 	/**
-	 * Constructor - Passes args to {@link WP_Ajax_Response::add()}.
+	 * Constructor - Passes args to WP_Ajax_Response::add().
 	 *
 	 * @since 2.1.0
 	 * @see WP_Ajax_Response::add()

wp-includes/class-wp-embed.php

@@ -43,7 +43,7 @@ class WP_Embed {
 	 *
 	 * Since the [embed] shortcode needs to be run earlier than other shortcodes,
 	 * this function removes all existing shortcodes, registers the [embed] shortcode,
-	 * calls {@link do_shortcode()}, and then re-registers the old shortcodes.
+	 * calls do_shortcode(), and then re-registers the old shortcodes.
 	 *
 	 * @global array $shortcode_tags
 	 *
@@ -88,7 +88,10 @@ class WP_Embed {
 	}
 
 	/**
-	 * Register an embed handler. Do not use this function directly, use {@link wp_embed_register_handler()} instead.
+	 * Registers an embed handler.
+	 *
+	 * Do not use this function directly, use wp_embed_register_handler() instead.
+	 *
 	 * This function should probably also only be used for sites that do not support oEmbed.
 	 *
 	 * @param string $id An internal ID/name for the handler. Needs to be unique.
@@ -104,7 +107,9 @@ class WP_Embed {
 	}
 
 	/**
-	 * Unregister a previously registered embed handler. Do not use this function directly, use {@link wp_embed_unregister_handler()} instead.
+	 * Unregisters a previously-registered embed handler.
+	 *
+	 * Do not use this function directly, use wp_embed_unregister_handler() instead.
 	 *
 	 * @param string $id The handler ID that should be removed.
 	 * @param int $priority Optional. The priority of the handler to be removed (default: 10).
@@ -114,10 +119,11 @@ class WP_Embed {
 	}
 
 	/**
-	 * The {@link do_shortcode()} callback function.
+	 * The do_shortcode() callback function.
 	 *
-	 * Attempts to convert a URL into embed HTML. Starts by checking the URL against the regex of the registered embed handlers.
+	 * Attempts to convert a URL into embed HTML. Starts by checking the URL against the regex of
-	 * If none of the regex matches and it's enabled, then the URL will be given to the {@link WP_oEmbed} class.
+	 * the registered embed handlers. If none of the regex matches and it's enabled, then the URL
+	 * will be given to the WP_oEmbed class.
 	 *
 	 * @param array $attr {
 	 *     Shortcode attributes. Optional.
@@ -312,9 +318,9 @@ class WP_Embed {
 	}
 
 	/**
-	 * Passes any unlinked URLs that are on their own line to {@link WP_Embed::shortcode()} for potential embedding.
+	 * Passes any unlinked URLs that are on their own line to WP_Embed::shortcode() for potential embedding.
 	 *
-	 * @uses WP_Embed::autoembed_callback()
+	 * @see WP_Embed::autoembed_callback()
 	 *
 	 * @param string $content The content to be searched.
 	 * @return string Potentially modified $content.
@@ -331,7 +337,7 @@ class WP_Embed {
 	}
 
 	/**
-	 * Callback function for {@link WP_Embed::autoembed()}.
+	 * Callback function for WP_Embed::autoembed().
 	 *
 	 * @param array $match A regex match array.
 	 * @return string The embed HTML on success, otherwise the original URL.

wp-includes/class-wp-error.php

@@ -11,8 +11,8 @@
  * WordPress Error class.
  *
  * Container for checking for WordPress errors and error messages. Return
- * WP_Error and use {@link is_wp_error()} to check if this class is returned.
+ * WP_Error and use is_wp_error() to check if this class is returned. Many
- * Many core WordPress functions pass this class in the event of an error and
+ * core WordPress functions pass this class in the event of an error and
  * if not handled properly will result in code errors.
  *
  * @package WordPress

wp-includes/class-wp-role.php

@@ -63,12 +63,12 @@ class WP_Role {
 	}
 
 	/**
-	 * Remove capability from role.
+	 * Removes a capability from a role.
 	 *
-	 * This is a container for {@link WP_Roles::remove_cap()} to remove the
+	 * This is a container for WP_Roles::remove_cap() to remove the
-	 * capability from the role. That is to say, that {@link
+	 * capability from the role. That is to say, that WP_Roles::remove_cap()
-	 * WP_Roles::remove_cap()} implements the functionality, but it also makes
+	 * implements the functionality, but it also makes sense to use this class,
-	 * sense to use this class, because you don't need to enter the role name.
+	 * because you don't need to enter the role name.
 	 *
 	 * @since 2.0.0
 	 * @access public

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

@@ -3112,7 +3112,7 @@ class wp_xmlrpc_server extends IXR_Server {
 	 *     @type string $password
 	 *     @type int    $category_id
 	 * }
-	 * @return bool|IXR_Error See {@link wp_delete_term()} for return info.
+	 * @return bool|IXR_Error See wp_delete_term() for return info.
 	 */
 	public function wp_deleteCategory( $args ) {
 		$this->escape( $args );
@@ -3244,7 +3244,7 @@ class wp_xmlrpc_server extends IXR_Server {
 	 * - 'status' - Default is ''. Filter by status (e.g., 'approve', 'hold')
 	 * - 'post_id' - Default is ''. The post where the comment is posted. Empty string shows all comments.
 	 * - 'number' - Default is 10. Total number of media items to retrieve.
-	 * - 'offset' - Default is 0. See {@link WP_Query::query()} for more.
+	 * - 'offset' - Default is 0. See WP_Query::query() for more.
 	 *
 	 * @since 2.7.0
 	 *
@@ -3256,7 +3256,7 @@ class wp_xmlrpc_server extends IXR_Server {
 	 *     @type string $password
 	 *     @type array  $struct
 	 * }
-	 * @return array|IXR_Error Contains a collection of comments. See {@link wp_xmlrpc_server::wp_getComment()} for a description of each item contents
+	 * @return array|IXR_Error Contains a collection of comments. See wp_xmlrpc_server::wp_getComment() for a description of each item contents
 	 */
 	public function wp_getComments( $args ) {
 		$this->escape( $args );
@@ -3328,8 +3328,7 @@ class wp_xmlrpc_server extends IXR_Server {
 	 * Delete a comment.
 	 *
 	 * By default, the comment will be moved to the trash instead of deleted.
-	 * See {@link wp_delete_comment()} for more information on
+	 * See wp_delete_comment() for more information on this behavior.
-	 * this behavior.
 	 *
 	 * @since 2.7.0
 	 *
@@ -3341,7 +3340,7 @@ class wp_xmlrpc_server extends IXR_Server {
 	 *     @type string $password
 	 *     @type int    $comment_ID
 	 * }
-	 * @return bool|IXR_Error {@link wp_delete_comment()}
+	 * @return bool|IXR_Error See wp_delete_comment().
 	 */
 	public function wp_deleteComment( $args ) {
 		$this->escape($args);
@@ -3498,7 +3497,7 @@ class wp_xmlrpc_server extends IXR_Server {
 	 *     @type string|int $post
 	 *     @type array      $content_struct
 	 * }
-	 * @return int|IXR_Error {@link wp_new_comment()}
+	 * @return int|IXR_Error See wp_new_comment().
 	 */
 	public function wp_newComment($args) {
 		$this->escape($args);

wp-includes/class-wp.php

@@ -718,7 +718,7 @@ class WP {
 	 * @since 2.0.0
 	 * @access public
 	 *
-	 * @param string|array $query_args Passed to {@link parse_request()}
+	 * @param string|array $query_args Passed to parse_request().
 	 */
 	public function main($query_args = '') {
 		$this->init();

wp-includes/comment.php

@@ -323,9 +323,8 @@ function get_lastcommentmodified($timezone = 'server') {
 /**
  * The amount of comments in a post or total comments.
  *
- * A lot like {@link wp_count_comments()}, in that they both return comment
+ * A lot like wp_count_comments(), in that they both return comment stats (albeit with different types).
- * stats (albeit with different types). The {@link wp_count_comments()} actual
+ * The wp_count_comments() actually caches, but this function does not.
- * caches, but this function does not.
  *
  * @since 2.0.0
  *

wp-includes/cron.php

@@ -457,7 +457,7 @@ function _get_cron_array()  {
  * @since 2.1.0
  * @access private
  *
- * @param array $cron Cron info array from {@link _get_cron_array()}.
+ * @param array $cron Cron info array from _get_cron_array().
  */
 function _set_cron_array($cron) {
 	$cron['version'] = 2;
@@ -472,7 +472,7 @@ function _set_cron_array($cron) {
  * @since 2.1.0
  * @access private
  *
- * @param array $cron Cron info array from {@link _get_cron_array()}.
+ * @param array $cron Cron info array from _get_cron_array().
  * @return array An upgraded Cron info array.
  */
 function _upgrade_cron_array($cron) {

wp-includes/deprecated.php

@@ -2126,7 +2126,7 @@ function register_sidebar_widget($name, $output_callback, $classname = '') {
 }
 
 /**
- * Alias of {@link wp_unregister_sidebar_widget()}.
+ * Serves as an alias of wp_unregister_sidebar_widget().
  *
  * @since 2.2.0
  * @deprecated 2.8.0 Use wp_unregister_sidebar_widget()

wp-includes/formatting.php

@@ -2104,8 +2104,7 @@ function antispambot( $email_address, $hex_encoding = 0 ) {
 /**
  * Callback to convert URI match to HTML A element.
  *
- * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
+ * This function was backported from 2.5.0 to 2.3.2. Regex callback for make_clickable().
- * make_clickable()}.
  *
  * @since 2.3.2
  * @access private
@@ -2141,8 +2140,7 @@ function _make_url_clickable_cb( $matches ) {
 /**
  * Callback to convert URL match to HTML A element.
  *
- * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
+ * This function was backported from 2.5.0 to 2.3.2. Regex callback for make_clickable().
- * make_clickable()}.
  *
  * @since 2.3.2
  * @access private
@@ -2171,8 +2169,7 @@ function _make_web_ftp_clickable_cb( $matches ) {
 /**
  * Callback to convert email address match to HTML A element.
  *
- * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
+ * This function was backported from 2.5.0 to 2.3.2. Regex callback for make_clickable().
- * make_clickable()}.
  *
  * @since 2.3.2
  * @access private
@@ -2367,7 +2364,8 @@ function wp_rel_nofollow_callback( $matches ) {
 /**
  * Convert one smiley code to the icon graphic file equivalent.
  *
- * Callback handler for {@link convert_smilies()}.
+ * Callback handler for convert_smilies().
+ *
  * Looks up one smiley code in the $wpsmiliestrans global array and returns an
  * `<img>` string for that smiley.
  *

wp-includes/general-template.php

@@ -2850,10 +2850,10 @@ function wp_editor( $content, $editor_id, $settings = array() ) {
 }
 
 /**
- * Retrieve the contents of the search WordPress query variable.
+ * Retrieves the contents of the search WordPress query variable.
  *
- * The search query string is passed through {@link esc_attr()}
+ * The search query string is passed through esc_attr() to ensure that it is safe
- * to ensure that it is safe for placing in an html attribute.
+ * for placing in an html attribute.
  *
  * @since 2.3.0
  *
@@ -2877,10 +2877,10 @@ function get_search_query( $escaped = true ) {
 }
 
 /**
- * Display the contents of the search query variable.
+ * Displays the contents of the search query variable.
  *
- * The search query string is passed through {@link esc_attr()}
+ * The search query string is passed through esc_attr() to ensure that it is safe
- * to ensure that it is safe for placing in an html attribute.
+ * for placing in an html attribute.
  *
  * @since 2.1.0
  */
@@ -2986,7 +2986,7 @@ function language_attributes( $doctype = 'html' ) {
  * numbers to either side of current page, but not including current page.
  *
  * It is possible to add query vars to the link by using the 'add_args' argument
- * and see {@link add_query_arg()} for more information.
+ * and see add_query_arg() for more information.
  *
  * The 'before_page_number' and 'after_page_number' arguments allow users to
  * augment the links themselves. Typically this might be to add context to the

wp-includes/post-template.php

@@ -56,12 +56,12 @@ function the_title( $before = '', $after = '', $echo = true ) {
 /**
  * Sanitize the current title when retrieving or displaying.
  *
- * Works like {@link the_title()}, except the parameters can be in a string or
+ * Works like the_title(), except the parameters can be in a string or
  * an array. See the function for what can be override in the $args parameter.
  *
- * The title before it is displayed will have the tags stripped and {@link
+ * The title before it is displayed will have the tags stripped and esc_attr()
- * esc_attr()} before it is passed to the user or displayed. The default
+ * before it is passed to the user or displayed. The default as with the_title(),
- * as with {@link the_title()}, is to display the title.
+ * is to display the title.
  *
  * @since 2.3.0
  *
@@ -1209,11 +1209,10 @@ function wp_list_pages( $args = '' ) {
 }
 
 /**
- * Display or retrieve list of pages with optional home link.
+ * Displays or retrieves a list of pages with an optional home link.
  *
- * The arguments are listed below and part of the arguments are for {@link
+ * The arguments are listed below and part of the arguments are for wp_list_pages()} function.
- * wp_list_pages()} function. Check that function for more info on those
+ * Check that function for more info on those arguments.
- * arguments.
  *
  * @since 2.7.0
  * @since 4.4.0 Added `menu_id`, `container`, `before`, `after`, and `walker` arguments.

wp-includes/post.php

@@ -286,11 +286,10 @@ function _wp_relative_upload_path( $path ) {
  * example of what is possible.
  *
  * The arguments listed as defaults are for this function and also of the
- * {@link get_posts()} function. The arguments are combined with the
+ * get_posts() function. The arguments are combined with the get_children defaults
- * get_children defaults and are then passed to the {@link get_posts()}
+ * and are then passed to the get_posts() function, which accepts additional arguments.
- * function, which accepts additional arguments. You can replace the defaults in
+ * You can replace the defaults in this function, listed below and the additional
- * this function, listed below and the additional arguments listed in the
+ * arguments listed in the get_posts() function.
- * {@link get_posts()} function.
  *
  * The 'post_parent' is the most important argument and important attention
  * needs to be paid to the $args parameter. If you pass either an object or an
@@ -412,8 +411,8 @@ function get_extended( $post ) {
 /**
  * Retrieves post data given a post ID or post object.
  *
- * See {@link sanitize_post()} for optional $filter values. Also, the parameter
+ * See sanitize_post() for optional $filter values. Also, the parameter
- * $post, must be given as a variable, since it is passed by reference.
+ * `$post`, must be given as a variable, since it is passed by reference.
  *
  * @since 1.5.1
  *
@@ -2870,7 +2869,7 @@ function wp_get_post_categories( $post_id = 0, $args = array() ) {
  *
  * There is only one default for this function, called 'fields' and by default
  * is set to 'all'. There are other defaults that can be overridden in
- * {@link wp_get_object_terms()}.
+ * wp_get_object_terms().
  *
  * @since 2.3.0
  *
@@ -2888,14 +2887,14 @@ function wp_get_post_tags( $post_id = 0, $args = array() ) {
  *
  * There is only one default for this function, called 'fields' and by default
  * is set to 'all'. There are other defaults that can be overridden in
- * {@link wp_get_object_terms()}.
+ * wp_get_object_terms().
  *
  * @since 2.8.0
  *
  * @param int    $post_id  Optional. The Post ID. Does not default to the ID of the
  *                         global $post. Default 0.
  * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'.
- * @param array  $args     Optional. {@link wp_get_object_terms()} arguments. Default empty array.
+ * @param array  $args     Optional. wp_get_object_terms() arguments. Default empty array.
  * @return array|WP_Error  List of post terms or empty array if no terms were found. WP_Error object
  *                         if `$taxonomy` doesn't exist.
  */

wp-includes/query.php

@@ -95,11 +95,11 @@ function query_posts($query) {
 }
 
 /**
- * Destroy the previous query and set up a new query.
+ * Destroys the previous query and sets up a new query.
  *
- * This should be used after {@link query_posts()} and before another {@link
+ * This should be used after query_posts() and before another query_posts().
- * query_posts()}. This will remove obscure bugs that occur when the previous
+ * This will remove obscure bugs that occur when the previous WP_Query object
- * wp_query object is not destroyed properly before another is set up.
+ * is not destroyed properly before another is set up.
  *
  * @since 2.3.0
  *

wp-includes/template.php

@@ -11,7 +11,7 @@
  *
  * Used to quickly retrieve the path of a template without including the file
  * extension. It will also check the parent theme, if the file exists, with
- * the use of {@link locate_template()}. Allows for more generic template location
+ * the use of locate_template(). Allows for more generic template location
  * without the use of the other get_*_template() functions.
  *
  * @since 1.5.0

wp-includes/theme.php

@@ -209,10 +209,10 @@ function get_stylesheet_directory_uri() {
 }
 
 /**
- * Retrieve URI of current theme stylesheet.
+ * Retrieves the URI of current theme stylesheet.
  *
- * The stylesheet file name is 'style.css' which is appended to {@link
+ * The stylesheet file name is 'style.css' which is appended to the stylesheet directory URI path.
- * get_stylesheet_directory_uri() stylesheet directory URI} path.
+ * See get_stylesheet_directory_uri().
  *
  * @since 1.5.0
  *

wp-includes/version.php

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