Changeset 37543

Timestamp:

05/23/2016 07:00:41 PM (9 years ago)

Author:

DrewAPicture

Message:

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.

See #36921.

Location:

trunk/src/wp-includes

Files:

• embed.php (modified) (1 diff)
• feed.php (modified) (1 diff)
• formatting.php (modified) (7 diffs)
• functions.php (modified) (7 diffs)
• functions.wp-scripts.php (modified) (1 diff)
• http.php (modified) (2 diffs)
• kses.php (modified) (5 diffs)
• link-template.php (modified) (2 diffs)
• media.php (modified) (5 diffs)

trunk/src/wp-includes/embed.php

@@ -51 +51 @@
  * The default height is 1.5 times the width, or 1000px, whichever is smaller.
  *
- * The 'embed_defaults' filter can be used to adjust either of these values.
+ * The {@see 'embed_defaults'} filter can be used to adjust either of these values.
  *
  * @since 2.9.0

trunk/src/wp-includes/feed.php

@@ -69 +69 @@
  *
  * The default feed is 'rss2', unless a plugin changes it through the
- * 'default_feed' filter.
+ * {@see 'default_feed'} filter.
  *
  * @since 2.5.0

trunk/src/wp-includes/formatting.php

@@ -21 +21 @@
  * Code within certain html blocks are skipped.
  *
- * Do not use this function before the 'init' action hook; everything will break.
+ * Do not use this function before the {@see 'init'} action hook; everything will break.
  *
  * @since 0.71
@@ -1442 +1442 @@
  * alphanumeric, _, space, ., -, @. After sanitizing, it passes the username,
  * raw username (the username in the parameter), and the value of $strict as
- * parameters for the 'sanitize_user' filter.
+ * parameters for the {@see 'sanitize_user'} filter.
  *
  * @since 2.0.0
@@ -1905 +1905 @@
  *
  * The $content is run through esc_textarea(), which uses htmlspecialchars()
- * to convert special characters to HTML entities. If $richedit is set to true,
- * it is simply a holder for the 'format_to_edit' filter.
+ * to convert special characters to HTML entities. If `$richedit` is set to true,
+ * it is simply a holder for the {@see 'format_to_edit'} filter.
  *
  * @since 0.71
@@ -2878 +2878 @@
  * is less than 55 words, then the content will be returned as is.
  *
- * The 55 word limit can be modified by plugins/themes using the excerpt_length filter
- * The ' […]' string can be modified by plugins/themes using the excerpt_more filter
+ * The 55 word limit can be modified by plugins/themes using the {@see 'excerpt_length'} filter
+ * The ' […]' string can be modified by plugins/themes using the {@see 'excerpt_more'} filter
  *
  * @since 1.5.0
@@ -3354 +3354 @@
  *
  * A number of characters are removed from the URL. If the URL is for displaying
- * (the default behaviour) ampersands are also replaced. The 'clean_url' filter
+ * (the default behaviour) ampersands are also replaced. The {@see 'clean_url'} filter
  * is applied to the returned cleaned URL.
  *
@@ -3363 +3363 @@
  *                          Defaults to return value of wp_allowed_protocols()
  * @param string $_context  Private. Use esc_url_raw() for database usage.
- * @return string The cleaned $url after the 'clean_url' filter is applied.
+ * @return string The cleaned $url after the {@see 'clean_url'} filter is applied.
  */
 function esc_url( $url, $protocols = null, $_context = 'display' ) {
@@ -3492 +3492 @@
  * Escapes text strings for echoing in JS. It is intended to be used for inline JS
  * (in a tag attribute, for example onclick="..."). Note that the strings have to
- * be in single quotes. The filter 'js_escape' is also applied here.
+ * be in single quotes. The {@see 'js_escape'} filter is also applied here.
  *
  * @since 2.8.0

trunk/src/wp-includes/functions.php

@@ -2319 +2319 @@
      *
      * This filter should be used to add, not remove, mime types. To remove
-     * mime types, use the 'upload_mimes' filter.
+     * mime types, use the {@see 'upload_mimes'} filter.
      *
      * @since 3.5.0
@@ -2592 +2592 @@
 
 /**
- * Kill WordPress execution and display HTML message with error message.
+ * Kills WordPress execution and display HTML message with error message.
  *
  * This is the default handler for wp_die if you want a custom one for your
- * site then you can overload using the wp_die_handler filter in wp_die
+ * site then you can overload using the {@see 'wp_die_handler'} filter in wp_die().
  *
  * @since 3.0.0
@@ -3631 +3631 @@
  * Mark a function as deprecated and inform when it has been used.
  *
- * There is a hook deprecated_function_run that will be called that can be used
+ * There is a {@see 'hook deprecated_function_run'} that will be called that can be used
  * to get the backtrace up to what file and function called the deprecated
  * function.
  *
- * The current behavior is to trigger a user error if WP_DEBUG is true.
+ * The current behavior is to trigger a user error if `WP_DEBUG` is true.
  *
  * This function is to be used in every function that is deprecated.
@@ -3751 +3751 @@
  * Mark a file as deprecated and inform when it has been used.
  *
- * There is a hook deprecated_file_included that will be called that can be used
+ * There is a hook {@see 'deprecated_file_included'} that will be called that can be used
  * to get the backtrace up to what file and function included the deprecated
  * file.
  *
- * The current behavior is to trigger a user error if WP_DEBUG is true.
+ * The current behavior is to trigger a user error if `WP_DEBUG` is true.
  *
  * This function is to be used in every file that is deprecated.
@@ -3868 +3868 @@
  * Mark something as being incorrectly called.
  *
- * There is a hook doing_it_wrong_run that will be called that can be used
+ * There is a hook {@see 'doing_it_wrong_run'} that will be called that can be used
  * to get the backtrace up to what file and function called the deprecated
  * function.
  *
- * The current behavior is to trigger a user error if WP_DEBUG is true.
+ * The current behavior is to trigger a user error if `WP_DEBUG` is true.
  *
  * @since 3.1.0
@@ -4573 +4573 @@
  * @param string $file            Path to the file.
  * @param array  $default_headers List of headers, in the format array('HeaderKey' => 'Header Name').
- * @param string $context         Optional. If specified adds filter hook "extra_{$context}_headers".
+ * @param string $context         Optional. If specified adds filter hook {@see 'extra_$context_headers'}.
  *                                Default empty.
  * @return array Array of file headers in `HeaderKey => Header Value` format.
@@ -4993 +4993 @@
  *
  * This is disabled for certain screens where a login screen could cause an
- * inconvenient interruption. A filter called wp_auth_check_load can be used
+ * inconvenient interruption. A filter called {@see 'wp_auth_check_load'} can be used
  * for fine-grained control.
  *

trunk/src/wp-includes/functions.wp-scripts.php

@@ -48 +48 @@
 
 /**
- * Print scripts in document head that are in the $handles queue.
- *
- * Called by admin-header.php and wp_head hook. Since it is called by wp_head on every page load,
+ * Prints scripts in document head that are in the $handles queue.
+ *
+ * Called by admin-header.php and {@see 'wp_head'} hook. Since it is called by wp_head on every page load,
  * the function does not instantiate the WP_Scripts object unless script names are explicitly passed.
- * Makes use of already-instantiated $wp_scripts global if present. Use provided wp_print_scripts
+ * Makes use of already-instantiated $wp_scripts global if present. Use provided {@see 'wp_print_scripts'}
  * hook to register/enqueue new scripts.
  *

trunk/src/wp-includes/http.php

@@ -582 +582 @@
  * Whitelists allowed redirect hosts for safe HTTP requests as well.
  *
- * Attached to the http_request_host_is_external filter.
+ * Attached to the {@see 'http_request_host_is_external'} filter.
  *
  * @since 3.6.0
@@ -599 +599 @@
  * Whitelists any domain in a multisite installation for safe HTTP requests.
  *
- * Attached to the http_request_host_is_external filter.
+ * Attached to the {@see 'http_request_host_is_external'} filter.
  *
  * @since 3.6.0

trunk/src/wp-includes/kses.php

@@ -35 +35 @@
  * You can override this in a plugin.
  *
- * The wp_kses_allowed_html filter is more powerful and supplies context.
- * CUSTOM_TAGS is not recommended and should be considered deprecated.
+ * The {@see 'wp_kses_allowed_html'} filter is more powerful and supplies context.
+ *
+ * `CUSTOM_TAGS` is not recommended and should be considered deprecated.
  *
  * @see wp_kses_allowed_html()
@@ -668 +669 @@
  * You add any kses hooks here.
  *
- * There is currently only one kses WordPress hook and it is called here. All
- * parameters are passed to the hooks and expected to receive a string.
+ * There is currently only one kses WordPress hook, {@see 'pre_kses'}, and it is called here.
+ * All parameters are passed to the hooks and expected to receive a string.
  *
  * @since 1.0.0
@@ -676 +677 @@
  * @param array  $allowed_html      List of allowed HTML elements
  * @param array  $allowed_protocols Allowed protocol in links
- * @return string Filtered content through 'pre_kses' hook
+ * @return string Filtered content through {@see 'pre_kses'} hook.
  */
 function wp_kses_hook( $string, $allowed_html, $allowed_protocols ) {
@@ -1642 +1643 @@
  * content in WordPress Loop.
  *
- * Does not remove the kses_init() function from 'init' hook (priority is
- * default). Also does not remove kses_init() function from 'set_current_user'
+ * Does not remove the kses_init() function from {@see 'init'} hook (priority is
+ * default). Also does not remove kses_init() function from {@see 'set_current_user'}
  * hook (priority is also default).
  *
@@ -1665 +1666 @@
  * Sets up most of the Kses filters for input form content.
  *
- * If you remove the kses_init() function from 'init' hook and
- * 'set_current_user' (priority is default), then none of the Kses filter hooks
+ * If you remove the kses_init() function from {@see 'init'} hook and
+ * {@see 'set_current_user'} (priority is default), then none of the Kses filter hooks
  * will be added.
  *

trunk/src/wp-includes/link-template.php

@@ -33 +33 @@
  * Conditionally adds a trailing slash if the permalink structure has a trailing
  * slash, strips the trailing slash if not. The string is passed through the
- * 'user_trailingslashit' filter. Will remove trailing slash from string, if
+ * {@see 'user_trailingslashit'} filter. Will remove trailing slash from string, if
  * site is not set to have them.
  *
@@ -3666 +3666 @@
  * Sends a Link: rel=shortlink header if a shortlink is defined for the current page.
  *
- * Attached to the wp action.
+ * Attached to the {@see 'wp'} action.
  *
  * @since 3.0.0

trunk/src/wp-includes/media.php

@@ -149 +149 @@
  * resized one if it exists.
  *
- * A plugin may use the 'image_downsize' filter to hook into and offer image
+ * A plugin may use the {@see 'image_downsize'} filter to hook into and offer image
  * resizing services for images. The hook must return an array with the same
  * elements that are returned in the function. The first element being the URL
@@ -310 +310 @@
  * Gets an img tag for an image attachment, scaling it down if requested.
  *
- * The filter 'get_image_tag_class' allows for changing the class name for the
+ * The {@see 'get_image_tag_class'} filter allows for changing the class name for the
  * image without having to use regular expressions on the HTML content. The
  * parameters are: what WordPress will use for the class, the Attachment ID,
  * image align value, and the size the image should be.
  *
- * The second filter 'get_image_tag' has the HTML content, which can then be
+ * The second filter, {@see 'get_image_tag'}, has the HTML content, which can then be
  * further manipulated by a plugin to change all attribute values and even HTML
  * content.
@@ -563 +563 @@
  *
  * The returned array has the file size, the image width, and image height. The
- * filter 'image_make_intermediate_size' can be used to hook in and change the
+ * {@see 'image_make_intermediate_size'} filter can be used to hook in and change the
  * values of the returned array. The only parameter is the resized file path.
  *
@@ -1388 +1388 @@
  * Adds a 'wp-post-image' class to post thumbnails. Internal use only.
  *
- * Uses the 'begin_fetch_post_thumbnail_html' and 'end_fetch_post_thumbnail_html' action hooks to
- * dynamically add/remove itself so as to only filter post thumbnails.
+ * Uses the {@see 'begin_fetch_post_thumbnail_html'} and {@see 'end_fetch_post_thumbnail_html'}
+ * action hooks to dynamically add/remove itself so as to only filter post thumbnails.
  *
  * @ignore
@@ -1435 +1435 @@
  *
  * Allows a plugin to replace the content that would otherwise be returned. The
- * filter is 'img_caption_shortcode' and passes an empty string, the attr
+ * filter is {@see 'img_caption_shortcode'} and passes an empty string, the attr
  * parameter and the content parameter values.
  *