From 3f494e00a380d2b8dc40c73653fd797fa7a036e3 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Mon, 24 Mar 2014 01:35:15 +0000 Subject: [PATCH] Inline documentation for hooks in wp-includes/category-template.php. Props kpdesign for the cleanup. Fixes #27432. Built from https://develop.svn.wordpress.org/trunk@27666 git-svn-id: http://core.svn.wordpress.org/trunk@27509 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/category-template.php | 173 +++++++++++++++++++++++++++--- 1 file changed, 159 insertions(+), 14 deletions(-) diff --git a/wp-includes/category-template.php b/wp-includes/category-template.php index 1e545ee69a..6cf21a20d8 100644 --- a/wp-includes/category-template.php +++ b/wp-includes/category-template.php @@ -82,7 +82,13 @@ function get_the_category( $id = false ) { _make_cat_compat( $categories[$key] ); } - // Filter name is plural because we return alot of categories (possibly more than #13237) not just one + /** + * Filter the array of categories to return for a post. + * + * @since 3.1.0 + * + * @param array $categories An array of categories to return for the post. + */ return apply_filters( 'get_the_categories', $categories ); } @@ -155,12 +161,16 @@ function get_the_category_by_ID( $cat_ID ) { */ function get_the_category_list( $separator = '', $parents='', $post_id = false ) { global $wp_rewrite; - if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) + if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) { + /** This filter is documented in wp-includes/category-template.php */ return apply_filters( 'the_category', '', $separator, $parents ); + } $categories = get_the_category( $post_id ); - if ( empty( $categories ) ) + if ( empty( $categories ) ) { + /** This filter is documented in wp-includes/category-template.php */ return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents ); + } $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"'; @@ -211,6 +221,17 @@ function get_the_category_list( $separator = '', $parents='', $post_id = false ) ++$i; } } + + /** + * Filter the category or list of categories. + * + * @since 1.2.0 + * + * @param array $thelist List of categories for the current post. + * @param string $separator Separator used between the categories. + * @param string $parents How to display the category parents. Accepts 'multiple', + * 'single', or empty. + */ return apply_filters( 'the_category', $thelist, $separator, $parents ); } @@ -344,6 +365,21 @@ function wp_dropdown_categories( $args = '' ) { $output = ''; if ( empty($categories) && ! $r['hide_if_empty'] && !empty($show_option_none) ) { + + /** + * Filter a taxonomy drop-down display element. + * + * A variety of taxonomy drop-down display elements can be modified + * just prior to display via this filter. Filterable arguments include + * 'show_option_none', 'show_option_all', and various forms of the + * term name. + * + * @since 1.2.0 + * + * @see wp_dropdown_categories() + * + * @param string $element Taxonomy element to list. + */ $show_option_none = apply_filters( 'list_cats', $show_option_none ); $output .= "\t\n"; } @@ -351,12 +387,16 @@ function wp_dropdown_categories( $args = '' ) { if ( ! empty( $categories ) ) { if ( $show_option_all ) { + + /** This filter is documented in wp-includes/category-template.php */ $show_option_all = apply_filters( 'list_cats', $show_option_all ); $selected = ( '0' === strval($r['selected']) ) ? " selected='selected'" : ''; $output .= "\t\n"; } if ( $show_option_none ) { + + /** This filter is documented in wp-includes/category-template.php */ $show_option_none = apply_filters( 'list_cats', $show_option_none ); $selected = ( '-1' === strval($r['selected']) ) ? " selected='selected'" : ''; $output .= "\t\n"; @@ -374,12 +414,12 @@ function wp_dropdown_categories( $args = '' ) { $output .= "\n"; /** - * Filter the result of wp_dropdown_categories(). + * Filter the taxonomy drop-down output. * * @since 2.1.0 * - * @param $output HTML content. - * @param $r Arguments used to build the dropdown. + * @param string $output HTML output. + * @param array $r Arguments used to build the drop-down. */ $output = apply_filters( 'wp_dropdown_cats', $output, $r ); @@ -493,6 +533,14 @@ function wp_list_categories( $args = '' ) { if ( $title_li && 'list' == $style ) $output .= ''; + /** + * Filter the HTML output of a taxonomy list. + * + * @since 2.1.0 + * + * @param string $output HTML output. + * @param array $args An array of taxonomy-listing arguments. + */ $output = apply_filters( 'wp_list_categories', $output, $args ); if ( $echo ) @@ -559,6 +607,14 @@ function wp_tag_cloud( $args = '' ) { $return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args + /** + * Filter the tag cloud output. + * + * @since 2.3.0 + * + * @param string $return HTML output of the tag cloud. + * @param array $args An array of tag cloud arguments. + */ $return = apply_filters( 'wp_tag_cloud', $return, $args ); if ( 'array' == $args['format'] || empty($args['echo']) ) @@ -644,8 +700,16 @@ function wp_generate_tag_cloud( $tags, $args = '' ) { $translate_nooped_plural = _n_noop( '%s topic', '%s topics' ); } + /** + * Filter how the items in a tag cloud are sorted. + * + * @since 2.8.0 + * + * @param array $tags Ordered array of terms. + * @param array $args An array of tag cloud arguments. + */ $tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args ); - if ( $tags_sorted != $tags ) { // the tags have been sorted by a plugin + if ( $tags_sorted != $tags ) { $tags = $tags_sorted; unset($tags_sorted); } else { @@ -716,8 +780,24 @@ function wp_generate_tag_cloud( $tags, $args = '' ) { break; endswitch; - if ( $filter ) + if ( $filter ) { + /** + * Filter the generated output of a tag cloud. + * + * The filter is only evaluated if a true value is passed + * to the $filter argument in wp_generate_tag_cloud(). + * + * @since 2.3.0 + * + * @see wp_generate_tag_cloud() + * + * @param string $return Generated HTML output of the tag cloud. + * @param array $tags An array of terms used in the tag cloud. + * @param array $args An array of wp_generate_tag_cloud() arguments. + */ return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args ); + } + else return $return; } @@ -866,12 +946,25 @@ class Walker_Category extends Walker { extract($args); $cat_name = esc_attr( $category->name ); + + /** This filter is documented in wp-includes/category-template.php */ $cat_name = apply_filters( 'list_cats', $cat_name, $category ); + $link = 'description) ) + if ( $use_desc_for_title == 0 || empty($category->description) ) { $link .= 'title="' . esc_attr( sprintf(__( 'View all posts filed under %s' ), $cat_name) ) . '"'; - else + } else { + /** + * Filter the category description for display. + * + * @since 1.2.0 + * + * @param string $description Category description. + * @param object $category Category object. + */ $link .= 'title="' . esc_attr( strip_tags( apply_filters( 'category_description', $category->description, $category ) ) ) . '"'; + } + $link .= '>'; $link .= $cat_name . ''; @@ -983,7 +1076,9 @@ class Walker_CategoryDropdown extends Walker { function start_el( &$output, $category, $depth = 0, $args = array(), $id = 0 ) { $pad = str_repeat(' ', $depth * 3); - $cat_name = apply_filters('list_cats', $category->name, $category); + /** This filter is documented in wp-includes/category-template.php */ + $cat_name = apply_filters( 'list_cats', $category->name, $category ); + $output .= "\t