Changeset 37542

Timestamp:

05/23/2016 06:58:48 PM (7 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:

• admin-bar.php (modified) (3 diffs)
• bookmark.php (modified) (2 diffs)
• category-template.php (modified) (1 diff)
• class-wp.php (modified) (2 diffs)
• comment-template.php (modified) (4 diffs)
• comment.php (modified) (3 diffs)
• cron.php (modified) (2 diffs)
• deprecated.php (modified) (6 diffs)

trunk/src/wp-includes/admin-bar.php

@@ -12 +12 @@
  *
  * UNHOOKING THIS FUNCTION WILL NOT PROPERLY REMOVE THE ADMIN BAR.
- * For that, use show_admin_bar(false) or the 'show_admin_bar' filter.
+ * For that, use show_admin_bar(false) or the {@see 'show_admin_bar'} filter.
  *
  * @since 3.1.0
@@ -52 +52 @@
 
 /**
- * Render the admin bar to the page based on the $wp_admin_bar->menu member var.
- * This is called very late on the footer actions so that it will render after anything else being
- * added to the footer.
- *
- * It includes the action "admin_bar_menu" which should be used to hook in and
- * add new menus to the admin bar. That way you can be sure that you are adding at most optimal point,
- * right before the admin bar is rendered. This also gives you access to the $post global, among others.
+ * Renders the admin bar to the page based on the $wp_admin_bar->menu member var.
+ *
+ * This is called very late on the footer actions so that it will render after
+ * anything else being added to the footer.
+ *
+ * It includes the {@see 'admin_bar_menu'} action which should be used to hook in and
+ * add new menus to the admin bar. That way you can be sure that you are adding at most
+ * optimal point, right before the admin bar is rendered. This also gives you access to
+ * the `$post` global, among others.
  *
  * @since 3.1.0
@@ -873 +875 @@
 
 /**
- * Set the display status of the admin bar.
- *
- * This can be called immediately upon plugin load. It does not need to be called from a function hooked to the init action.
+ * Sets the display status of the admin bar.
+ *
+ * This can be called immediately upon plugin load. It does not need to be called
+ * from a function hooked to the {@see 'init'} action.
  *
  * @since 3.1.0

trunk/src/wp-includes/bookmark.php

@@ -330 +330 @@
 
 /**
- * Sanitizes a bookmark field
+ * Sanitizes a bookmark field.
  *
  * Sanitizes the bookmark fields based on what the field name is. If the field
@@ -338 +338 @@
  *
  * Hooks exist for the more generic cases. With the 'edit' context, the
- * 'edit_$field' filter will be called and passed the $value and $bookmark_id
- * respectively. With the 'db' context, the 'pre_$field' filter is called and
+ * {@see 'edit_$field'} filter will be called and passed the `$value` and `$bookmark_id`
+ * respectively. With the 'db' context, the {@see 'pre_$field'} filter is called and
  * passed the value. The 'display' context is the final context and has the
- * $field has the filter name and is passed the $value, $bookmark_id, and
- * $context respectively.
+ * `$field` has the filter name and is passed the `$value`, `$bookmark_id`, and
+ * `$context`, respectively.
  *
  * @since 2.3.0

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

@@ -778 +778 @@
  * the 'format' argument will return in PHP array type format.
  *
- * The 'tag_cloud_sort' filter allows you to override the sorting.
+ * The {@see 'tag_cloud_sort'} filter allows you to override the sorting.
  * Passed to the filter: $tags array and $args array, has to return the $tags array
  * after sorting it.

trunk/src/wp-includes/class-wp.php

@@ -514 +514 @@
      * Sets the query string property based off of the query variable property.
      *
-     * The 'query_string' filter is deprecated, but still works. Plugins should
-     * use the 'request' filter instead.
+     * The {@see 'query_string'} filter is deprecated, but still works. Plugins should
+     * use the {@see 'request'} filter instead.
      *
      * @since 2.0.0
@@ -712 +712 @@
      * Sets up all of the variables required by the WordPress environment.
      *
-     * The action 'wp' has one parameter that references the WP object. It
+     * The action {@see 'wp'} has one parameter that references the WP object. It
      * allows for accessing the properties and methods to further manipulate the
      * object.

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

@@ -1240 +1240 @@
  *
  * Uses the WordPress database object to query for the comments. The comments
- * are passed through the 'comments_array' filter hook with the list of comments
+ * are passed through the {@see 'comments_array'} filter hook with the list of comments
  * and the post ID respectively.
  *
- * The $file path is passed through a filter hook called, 'comments_template'
+ * The `$file` path is passed through a filter hook called {@see 'comments_template'},
  * which includes the TEMPLATEPATH and $file combined. Tries the $filtered path
  * first and if it fails it will require the default comment template from the
@@ -2070 +2070 @@
 
 /**
- * Output a complete commenting form for use within a template.
+ * Outputs a complete commenting form for use within a template.
  *
  * Most strings and form fields may be controlled through the $args array passed
- * into the function, while you may also choose to use the comment_form_default_fields
+ * into the function, while you may also choose to use the {@see 'comment_form_default_fields'}
  * filter to modify the array of default fields if you'd just like to add a new
  * one or remove a single field. All fields are also individually passed through
- * a filter of the form comment_form_field_$name where $name is the key used
+ * a filter of the {@see 'form comment_form_field_$name'} where $name is the key used
  * in the array of fields.
  *
@@ -2092 +2092 @@
  *
  *     @type array $fields {
- *         Default comment fields, filterable by default via the 'comment_form_default_fields' hook.
+ *         Default comment fields, filterable by default via the {@see 'comment_form_default_fields'} hook.
  *
  *         @type string $author Comment author field HTML.
@@ -2209 +2209 @@
      * Filters the comment form default arguments.
      *
-     * Use 'comment_form_default_fields' to filter the comment fields.
+     * Use {@see 'comment_form_default_fields'} to filter the comment fields.
      *
      * @since 3.0.0

trunk/src/wp-includes/comment.php

@@ -1410 +1410 @@
  * Calls hooks for comment status transitions. If the new comment status is not the same
  * as the previous comment status, then two hooks will be ran, the first is
- * 'transition_comment_status' with new status, old status, and comment data. The
- * next action called is 'comment_OLDSTATUS_to_NEWSTATUS' the NEWSTATUS is the
- * $new_status parameter and the OLDSTATUS is $old_status parameter; it has the
+ * {@see 'transition_comment_status'} with new status, old status, and comment data. The
+ * next action called is {@see comment_$old_status_to_$new_status'}. It has the
  * comment data.
  *
  * The final action will run whether or not the comment statuses are the same. The
- * action is named 'comment_NEWSTATUS_COMMENTTYPE', NEWSTATUS is from the $new_status
- * parameter and COMMENTTYPE is comment_type comment data.
+ * action is named {@see 'comment_$new_status_$comment->comment_type'}.
  *
  * @since 2.7.0
@@ -1701 +1699 @@
  *
  * Filters new comment to ensure that the fields are sanitized and valid before
- * inserting comment into database. Calls 'comment_post' action with comment ID
- * and whether comment is approved by WordPress. Also has 'preprocess_comment'
+ * inserting comment into database. Calls {@see 'comment_post'} action with comment ID
+ * and whether comment is approved by WordPress. Also has {@see 'preprocess_comment'}
  * filter for processing the comment data before the function handles it.
  *
- * We use REMOTE_ADDR here directly. If you are behind a proxy, you should ensure
+ * We use `REMOTE_ADDR` here directly. If you are behind a proxy, you should ensure
  * that it is properly set, such as in wp-config.php, for your environment.
+ *
  * See {@link https://core.trac.wordpress.org/ticket/9235}
  *
@@ -1892 +1891 @@
  * Sets the status of a comment.
  *
- * The 'wp_set_comment_status' action is called after the comment is handled.
+ * The {@see 'wp_set_comment_status'} action is called after the comment is handled.
  * If the comment status is not in the list, then false is returned.
  *

trunk/src/wp-includes/cron.php

@@ -63 +63 @@
  *
  * Valid values for the recurrence are hourly, daily and twicedaily. These can
- * be extended using the cron_schedules filter in wp_get_schedules().
+ * be extended using the {@see 'cron_schedules'} filter in wp_get_schedules().
  *
  * Use wp_next_scheduled() to prevent duplicates
@@ -364 +364 @@
  *
  * The supported recurrences are 'hourly' and 'daily'. A plugin may add more by
- * hooking into the 'cron_schedules' filter. The filter accepts an array of
+ * hooking into the {@see 'cron_schedules'} filter. The filter accepts an array of
  * arrays. The outer array has a key that is the name of the schedule or for
  * example 'weekly'. The value is an array with two keys, one is 'interval' and

trunk/src/wp-includes/deprecated.php

@@ -2021 +2021 @@
  * @param array $protocols Optional. An array of acceptable protocols.
  * @param string $context Optional. How the URL will be used. Default is 'display'.
- * @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 clean_url( $url, $protocols = null, $context = 'display' ) {
@@ -2034 +2034 @@
  * Escape single quotes, specialchar double quotes, and fix line endings.
  *
- * The filter 'js_escape' is also applied by esc_js()
+ * The filter {@see 'js_escape'} is also applied by esc_js().
  *
  * @since 2.0.4
@@ -2969 +2969 @@
  * @see add_theme_support()
  *
- * @param callable $wp_head_callback Call on 'wp_head' action.
+ * @param callable $wp_head_callback Call on the {@see 'wp_head'} action.
  * @param callable $admin_head_callback Call on custom header administration screen.
  * @param callable $admin_preview_callback Output a custom header image div on the custom header administration screen. Optional.
@@ -3005 +3005 @@
  * @see add_theme_support()
  *
- * @param callable $wp_head_callback Call on 'wp_head' action.
+ * @param callable $wp_head_callback Call on the {@see 'wp_head'} action.
  * @param callable $admin_head_callback Call on custom background administration screen.
  * @param callable $admin_preview_callback Output a custom background image div on the custom background administration screen. Optional.
@@ -3525 +3525 @@
  * Formats text for the rich text editor.
  *
- * The filter 'richedit_pre' is applied here. If $text is empty the filter will
+ * The {@see 'richedit_pre'} filter is applied here. If $text is empty the filter will
  * be applied to an empty string.
  *
@@ -3568 +3568 @@
  *
  * Unless $output is empty it will pass through htmlspecialchars before the
- * 'htmledit_pre' filter is applied.
+ * {@see 'htmledit_pre'} filter is applied.
  *
  * @since 2.5.0