WordPress.org

Make WordPress Core

Changeset 37543


Ignore:
Timestamp:
05/23/2016 07:00:41 PM (3 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:
9 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/embed.php

    r37513 r37543  
    5151 * The default height is 1.5 times the width, or 1000px, whichever is smaller.
    5252 *
    53  * The 'embed_defaults' filter can be used to adjust either of these values.
     53 * The {@see 'embed_defaults'} filter can be used to adjust either of these values.
    5454 *
    5555 * @since 2.9.0
  • trunk/src/wp-includes/feed.php

    r37516 r37543  
    6969 *
    7070 * The default feed is 'rss2', unless a plugin changes it through the
    71  * 'default_feed' filter.
     71 * {@see 'default_feed'} filter.
    7272 *
    7373 * @since 2.5.0
  • trunk/src/wp-includes/formatting.php

    r37515 r37543  
    2121 * Code within certain html blocks are skipped.
    2222 *
    23  * Do not use this function before the 'init' action hook; everything will break.
     23 * Do not use this function before the {@see 'init'} action hook; everything will break.
    2424 *
    2525 * @since 0.71
     
    14421442 * alphanumeric, _, space, ., -, @. After sanitizing, it passes the username,
    14431443 * raw username (the username in the parameter), and the value of $strict as
    1444  * parameters for the 'sanitize_user' filter.
     1444 * parameters for the {@see 'sanitize_user'} filter.
    14451445 *
    14461446 * @since 2.0.0
     
    19051905 *
    19061906 * The $content is run through esc_textarea(), which uses htmlspecialchars()
    1907  * to convert special characters to HTML entities. If $richedit is set to true,
    1908  * it is simply a holder for the 'format_to_edit' filter.
     1907 * to convert special characters to HTML entities. If `$richedit` is set to true,
     1908 * it is simply a holder for the {@see 'format_to_edit'} filter.
    19091909 *
    19101910 * @since 0.71
     
    28782878 * is less than 55 words, then the content will be returned as is.
    28792879 *
    2880  * The 55 word limit can be modified by plugins/themes using the excerpt_length filter
    2881  * The ' […]' string can be modified by plugins/themes using the excerpt_more filter
     2880 * The 55 word limit can be modified by plugins/themes using the {@see 'excerpt_length'} filter
     2881 * The ' […]' string can be modified by plugins/themes using the {@see 'excerpt_more'} filter
    28822882 *
    28832883 * @since 1.5.0
     
    33543354 *
    33553355 * A number of characters are removed from the URL. If the URL is for displaying
    3356  * (the default behaviour) ampersands are also replaced. The 'clean_url' filter
     3356 * (the default behaviour) ampersands are also replaced. The {@see 'clean_url'} filter
    33573357 * is applied to the returned cleaned URL.
    33583358 *
     
    33633363 *                          Defaults to return value of wp_allowed_protocols()
    33643364 * @param string $_context  Private. Use esc_url_raw() for database usage.
    3365  * @return string The cleaned $url after the 'clean_url' filter is applied.
     3365 * @return string The cleaned $url after the {@see 'clean_url'} filter is applied.
    33663366 */
    33673367function esc_url( $url, $protocols = null, $_context = 'display' ) {
     
    34923492 * Escapes text strings for echoing in JS. It is intended to be used for inline JS
    34933493 * (in a tag attribute, for example onclick="..."). Note that the strings have to
    3494  * be in single quotes. The filter 'js_escape' is also applied here.
     3494 * be in single quotes. The {@see 'js_escape'} filter is also applied here.
    34953495 *
    34963496 * @since 2.8.0
  • trunk/src/wp-includes/functions.php

    r37510 r37543  
    23192319     *
    23202320     * This filter should be used to add, not remove, mime types. To remove
    2321      * mime types, use the 'upload_mimes' filter.
     2321     * mime types, use the {@see 'upload_mimes'} filter.
    23222322     *
    23232323     * @since 3.5.0
     
    25922592
    25932593/**
    2594  * Kill WordPress execution and display HTML message with error message.
     2594 * Kills WordPress execution and display HTML message with error message.
    25952595 *
    25962596 * This is the default handler for wp_die if you want a custom one for your
    2597  * site then you can overload using the wp_die_handler filter in wp_die
     2597 * site then you can overload using the {@see 'wp_die_handler'} filter in wp_die().
    25982598 *
    25992599 * @since 3.0.0
     
    36313631 * Mark a function as deprecated and inform when it has been used.
    36323632 *
    3633  * There is a hook deprecated_function_run that will be called that can be used
     3633 * There is a {@see 'hook deprecated_function_run'} that will be called that can be used
    36343634 * to get the backtrace up to what file and function called the deprecated
    36353635 * function.
    36363636 *
    3637  * The current behavior is to trigger a user error if WP_DEBUG is true.
     3637 * The current behavior is to trigger a user error if `WP_DEBUG` is true.
    36383638 *
    36393639 * This function is to be used in every function that is deprecated.
     
    37513751 * Mark a file as deprecated and inform when it has been used.
    37523752 *
    3753  * There is a hook deprecated_file_included that will be called that can be used
     3753 * There is a hook {@see 'deprecated_file_included'} that will be called that can be used
    37543754 * to get the backtrace up to what file and function included the deprecated
    37553755 * file.
    37563756 *
    3757  * The current behavior is to trigger a user error if WP_DEBUG is true.
     3757 * The current behavior is to trigger a user error if `WP_DEBUG` is true.
    37583758 *
    37593759 * This function is to be used in every file that is deprecated.
     
    38683868 * Mark something as being incorrectly called.
    38693869 *
    3870  * There is a hook doing_it_wrong_run that will be called that can be used
     3870 * There is a hook {@see 'doing_it_wrong_run'} that will be called that can be used
    38713871 * to get the backtrace up to what file and function called the deprecated
    38723872 * function.
    38733873 *
    3874  * The current behavior is to trigger a user error if WP_DEBUG is true.
     3874 * The current behavior is to trigger a user error if `WP_DEBUG` is true.
    38753875 *
    38763876 * @since 3.1.0
     
    45734573 * @param string $file            Path to the file.
    45744574 * @param array  $default_headers List of headers, in the format array('HeaderKey' => 'Header Name').
    4575  * @param string $context         Optional. If specified adds filter hook "extra_{$context}_headers".
     4575 * @param string $context         Optional. If specified adds filter hook {@see 'extra_$context_headers'}.
    45764576 *                                Default empty.
    45774577 * @return array Array of file headers in `HeaderKey => Header Value` format.
     
    49934993 *
    49944994 * This is disabled for certain screens where a login screen could cause an
    4995  * inconvenient interruption. A filter called wp_auth_check_load can be used
     4995 * inconvenient interruption. A filter called {@see 'wp_auth_check_load'} can be used
    49964996 * for fine-grained control.
    49974997 *
  • trunk/src/wp-includes/functions.wp-scripts.php

    r37191 r37543  
    4848
    4949/**
    50  * Print scripts in document head that are in the $handles queue.
    51  *
    52  * Called by admin-header.php and wp_head hook. Since it is called by wp_head on every page load,
     50 * Prints scripts in document head that are in the $handles queue.
     51 *
     52 * Called by admin-header.php and {@see 'wp_head'} hook. Since it is called by wp_head on every page load,
    5353 * the function does not instantiate the WP_Scripts object unless script names are explicitly passed.
    54  * Makes use of already-instantiated $wp_scripts global if present. Use provided wp_print_scripts
     54 * Makes use of already-instantiated $wp_scripts global if present. Use provided {@see 'wp_print_scripts'}
    5555 * hook to register/enqueue new scripts.
    5656 *
  • trunk/src/wp-includes/http.php

    r37428 r37543  
    582582 * Whitelists allowed redirect hosts for safe HTTP requests as well.
    583583 *
    584  * Attached to the http_request_host_is_external filter.
     584 * Attached to the {@see 'http_request_host_is_external'} filter.
    585585 *
    586586 * @since 3.6.0
     
    599599 * Whitelists any domain in a multisite installation for safe HTTP requests.
    600600 *
    601  * Attached to the http_request_host_is_external filter.
     601 * Attached to the {@see 'http_request_host_is_external'} filter.
    602602 *
    603603 * @since 3.6.0
  • trunk/src/wp-includes/kses.php

    r37518 r37543  
    3535 * You can override this in a plugin.
    3636 *
    37  * The wp_kses_allowed_html filter is more powerful and supplies context.
    38  * CUSTOM_TAGS is not recommended and should be considered deprecated.
     37 * The {@see 'wp_kses_allowed_html'} filter is more powerful and supplies context.
     38 *
     39 * `CUSTOM_TAGS` is not recommended and should be considered deprecated.
    3940 *
    4041 * @see wp_kses_allowed_html()
     
    668669 * You add any kses hooks here.
    669670 *
    670  * There is currently only one kses WordPress hook and it is called here. All
    671  * parameters are passed to the hooks and expected to receive a string.
     671 * There is currently only one kses WordPress hook, {@see 'pre_kses'}, and it is called here.
     672 * All parameters are passed to the hooks and expected to receive a string.
    672673 *
    673674 * @since 1.0.0
     
    676677 * @param array  $allowed_html      List of allowed HTML elements
    677678 * @param array  $allowed_protocols Allowed protocol in links
    678  * @return string Filtered content through 'pre_kses' hook
     679 * @return string Filtered content through {@see 'pre_kses'} hook.
    679680 */
    680681function wp_kses_hook( $string, $allowed_html, $allowed_protocols ) {
     
    16421643 * content in WordPress Loop.
    16431644 *
    1644  * Does not remove the kses_init() function from 'init' hook (priority is
    1645  * default). Also does not remove kses_init() function from 'set_current_user'
     1645 * Does not remove the kses_init() function from {@see 'init'} hook (priority is
     1646 * default). Also does not remove kses_init() function from {@see 'set_current_user'}
    16461647 * hook (priority is also default).
    16471648 *
     
    16651666 * Sets up most of the Kses filters for input form content.
    16661667 *
    1667  * If you remove the kses_init() function from 'init' hook and
    1668  * 'set_current_user' (priority is default), then none of the Kses filter hooks
     1668 * If you remove the kses_init() function from {@see 'init'} hook and
     1669 * {@see 'set_current_user'} (priority is default), then none of the Kses filter hooks
    16691670 * will be added.
    16701671 *
  • trunk/src/wp-includes/link-template.php

    r37499 r37543  
    3333 * Conditionally adds a trailing slash if the permalink structure has a trailing
    3434 * slash, strips the trailing slash if not. The string is passed through the
    35  * 'user_trailingslashit' filter. Will remove trailing slash from string, if
     35 * {@see 'user_trailingslashit'} filter. Will remove trailing slash from string, if
    3636 * site is not set to have them.
    3737 *
     
    36663666 * Sends a Link: rel=shortlink header if a shortlink is defined for the current page.
    36673667 *
    3668  * Attached to the wp action.
     3668 * Attached to the {@see 'wp'} action.
    36693669 *
    36703670 * @since 3.0.0
  • trunk/src/wp-includes/media.php

    r37505 r37543  
    149149 * resized one if it exists.
    150150 *
    151  * A plugin may use the 'image_downsize' filter to hook into and offer image
     151 * A plugin may use the {@see 'image_downsize'} filter to hook into and offer image
    152152 * resizing services for images. The hook must return an array with the same
    153153 * elements that are returned in the function. The first element being the URL
     
    310310 * Gets an img tag for an image attachment, scaling it down if requested.
    311311 *
    312  * The filter 'get_image_tag_class' allows for changing the class name for the
     312 * The {@see 'get_image_tag_class'} filter allows for changing the class name for the
    313313 * image without having to use regular expressions on the HTML content. The
    314314 * parameters are: what WordPress will use for the class, the Attachment ID,
    315315 * image align value, and the size the image should be.
    316316 *
    317  * The second filter 'get_image_tag' has the HTML content, which can then be
     317 * The second filter, {@see 'get_image_tag'}, has the HTML content, which can then be
    318318 * further manipulated by a plugin to change all attribute values and even HTML
    319319 * content.
     
    563563 *
    564564 * The returned array has the file size, the image width, and image height. The
    565  * filter 'image_make_intermediate_size' can be used to hook in and change the
     565 * {@see 'image_make_intermediate_size'} filter can be used to hook in and change the
    566566 * values of the returned array. The only parameter is the resized file path.
    567567 *
     
    13881388 * Adds a 'wp-post-image' class to post thumbnails. Internal use only.
    13891389 *
    1390  * Uses the 'begin_fetch_post_thumbnail_html' and 'end_fetch_post_thumbnail_html' action hooks to
    1391  * dynamically add/remove itself so as to only filter post thumbnails.
     1390 * Uses the {@see 'begin_fetch_post_thumbnail_html'} and {@see 'end_fetch_post_thumbnail_html'}
     1391 * action hooks to dynamically add/remove itself so as to only filter post thumbnails.
    13921392 *
    13931393 * @ignore
     
    14351435 *
    14361436 * Allows a plugin to replace the content that would otherwise be returned. The
    1437  * filter is 'img_caption_shortcode' and passes an empty string, the attr
     1437 * filter is {@see 'img_caption_shortcode'} and passes an empty string, the attr
    14381438 * parameter and the content parameter values.
    14391439 *
Note: See TracChangeset for help on using the changeset viewer.