Ticket #5634: 5634.r8970.diff

File 5634.r8970.diff, 19.1 KB (added by jacobsantos, 4 years ago)

Complete inline documentation for category-template.php based off of r8970

  • category-template.php

     
    11<?php 
     2/** 
     3 * Category Template Tags and API. 
     4 * 
     5 * @package WordPress 
     6 * @subpackage Template 
     7 */ 
    28 
     9/** 
     10 * Retrieve category children list separated before and after the term IDs. 
     11 * 
     12 * @since 1.2.0 
     13 * 
     14 * @param int $id Category ID to retrieve children. 
     15 * @param string $before Optional. Prepend before category term ID. 
     16 * @param string $after Optional, default is empty string. Append after category term ID. 
     17 * @param array $visited Optional. Category Term IDs that have already been added. 
     18 * @return string 
     19 */ 
    320function get_category_children( $id, $before = '/', $after = '', $visited = array() ) { 
    421        if ( 0 == $id ) 
    522                return ''; 
    623 
    724        $chain = ''; 
    8         // TODO: consult hierarchy 
     25        /** TODO: consult hierarchy */ 
    926        $cat_ids = get_all_category_ids(); 
    1027        foreach ( (array) $cat_ids as $cat_id ) { 
    1128                if ( $cat_id == $id ) 
    … …  
    2340        return $chain; 
    2441} 
    2542 
     43/** 
     44 * Retrieve category link URL. 
     45 * 
     46 * @since 1.0.0 
     47 * @uses apply_filters() Calls 'category_link' filter on category link and category ID. 
     48 * 
     49 * @param int $category_id Category ID. 
     50 * @return string 
     51 */ 
    2652function get_category_link( $category_id ) { 
    2753        global $wp_rewrite; 
    2854        $catlink = $wp_rewrite->get_category_permastruct(); 
    … …  
    4571        return apply_filters( 'category_link', $catlink, $category_id ); 
    4672} 
    4773 
    48 function get_category_parents( $id, $link = FALSE, $separator = '/', $nicename = FALSE, $visited = array() ) { 
     74/** 
     75 * Retrieve category parents with separator. 
     76 * 
     77 * @since 1.2.0 
     78 * 
     79 * @param int $id Category ID. 
     80 * @param bool $link Optional, default is false. Whether to format with link. 
     81 * @param string $separator Optional, default is '/'. How to separate categories. 
     82 * @param bool $nicename Optional, default is false. Whether to use nice name for display. 
     83 * @param array $visited Optional. Already linked to categories to prevent duplicates. 
     84 * @return string 
     85 */ 
     86function get_category_parents( $id, $link = false, $separator = '/', $nicename = false, $visited = array() ) { 
    4987        $chain = ''; 
    5088        $parent = &get_category( $id ); 
    5189        if ( is_wp_error( $parent ) ) 
    … …  
    68106        return $chain; 
    69107} 
    70108 
     109/** 
     110 * Retrieve post categories. 
     111 * 
     112 * @since 0.71 
     113 * @uses $post 
     114 * 
     115 * @param int $id Optional, default to current post ID. The post ID. 
     116 * @return array 
     117 */ 
    71118function get_the_category( $id = false ) { 
    72119        global $post; 
    73120 
    … …  
    91138        return $categories; 
    92139} 
    93140 
     141/** 
     142 * Sort categories by name. 
     143 * 
     144 * Used by usort() as a callback, should not be used directly. Can actually be 
     145 * used to sort any term object. 
     146 * 
     147 * @since 2.3.0 
     148 * @access private 
     149 * 
     150 * @param object $a 
     151 * @param object $b 
     152 * @return int 
     153 */ 
    94154function _usort_terms_by_name( $a, $b ) { 
    95155        return strcmp( $a->name, $b->name ); 
    96156} 
    97157 
     158/** 
     159 * Sort categories by ID. 
     160 * 
     161 * Used by usort() as a callback, should not be used directly. Can actually be 
     162 * used to sort any term object. 
     163 * 
     164 * @since 2.3.0 
     165 * @access private 
     166 * 
     167 * @param object $a 
     168 * @param object $b 
     169 * @return int 
     170 */ 
    98171function _usort_terms_by_ID( $a, $b ) { 
    99172        if ( $a->term_id > $b->term_id ) 
    100173                return 1; 
    … …  
    104177                return 0; 
    105178} 
    106179 
     180/** 
     181 * Retrieve category name based on category ID. 
     182 * 
     183 * @since 0.71 
     184 * 
     185 * @param int $cat_ID Category ID. 
     186 * @return string Category name. 
     187 */ 
    107188function get_the_category_by_ID( $cat_ID ) { 
    108189        $cat_ID = (int) $cat_ID; 
    109190        $category = &get_category( $cat_ID ); 
    … …  
    112193        return $category->name; 
    113194} 
    114195 
     196/** 
     197 * Retrieve category list in either HTML list or custom format. 
     198 * 
     199 * @since 1.5.1 
     200 * 
     201 * @param string $separator Optional, default is empty string. Separator for between the categories. 
     202 * @param string $parents Optional. How to display the parents. 
     203 * @param int $post_id Optional. Post ID to retrieve categories. 
     204 * @return string 
     205 */ 
    115206function get_the_category_list( $separator = '', $parents='', $post_id = false ) { 
    116207        global $wp_rewrite; 
    117208        $categories = get_the_category( $post_id ); 
    … …  
    128219                        switch ( strtolower( $parents ) ) { 
    129220                                case 'multiple': 
    130221                                        if ( $category->parent ) 
    131                                                 $thelist .= get_category_parents( $category->parent, TRUE ); 
     222                                                $thelist .= get_category_parents( $category->parent, true ); 
    132223                                        $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>' . $category->name.'</a></li>'; 
    133224                                        break; 
    134225                                case 'single': 
    135226                                        $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>'; 
    136227                                        if ( $category->parent ) 
    137                                                 $thelist .= get_category_parents( $category->parent, FALSE ); 
     228                                                $thelist .= get_category_parents( $category->parent, false ); 
    138229                                        $thelist .= $category->name.'</a></li>'; 
    139230                                        break; 
    140231                                case '': 
    … …  
    151242                        switch ( strtolower( $parents ) ) { 
    152243                                case 'multiple': 
    153244                                        if ( $category->parent ) 
    154                                                 $thelist .= get_category_parents( $category->parent, TRUE ); 
     245                                                $thelist .= get_category_parents( $category->parent, true ); 
    155246                                        $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>' . $category->cat_name.'</a>'; 
    156247                                        break; 
    157248                                case 'single': 
    158249                                        $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>'; 
    159250                                        if ( $category->parent ) 
    160                                                 $thelist .= get_category_parents( $category->parent, FALSE ); 
     251                                                $thelist .= get_category_parents( $category->parent, false ); 
    161252                                        $thelist .= "$category->cat_name</a>"; 
    162253                                        break; 
    163254                                case '': 
    … …  
    170261        return apply_filters( 'the_category', $thelist, $separator, $parents ); 
    171262} 
    172263 
    173 /* 
    174  * in_category() - Checks whether the current post is within a particular category 
     264/** 
     265 * Checks whether the current post is within a particular category. 
    175266 * 
    176  * This function checks to see if the post is within the supplied category.  The categoy 
    177  * can be specified by number or name and will be checked as a name first to allow for categories with numeric names. 
    178  * Note: Prior to v2.5 of WordPress category names where not supported. 
     267 * This function checks to see if the post is within the supplied category. The 
     268 * category can be specified by number or name and will be checked as a name 
     269 * first to allow for categories with numeric names. Note: Prior to v2.5 of 
     270 * WordPress category names were not supported. 
    179271 * 
    180272 * @since 1.2.0 
    181273 * 
    182  * @param int|string $category 
    183  * @return bool true if the post is in the supplied category 
     274 * @param int|string $category Category ID or category name. 
     275 * @return bool True, if the post is in the supplied category. 
    184276*/ 
    185 function in_category( $category ) { // Check if the current post is in the given category 
     277function in_category( $category ) { 
    186278        global $post; 
    187279 
    188280        if ( empty( $category ) ) 
    … …  
    204296                return false; 
    205297} 
    206298 
     299/** 
     300 * Display the category list for the post. 
     301 * 
     302 * @since 0.71 
     303 * 
     304 * @param string $separator Optional, default is empty string. Separator for between the categories. 
     305 * @param string $parents Optional. How to display the parents. 
     306 * @param int $post_id Optional. Post ID to retrieve categories. 
     307 */ 
    207308function the_category( $separator = '', $parents='', $post_id = false ) { 
    208309        echo get_the_category_list( $separator, $parents, $post_id ); 
    209310} 
    210311 
     312/** 
     313 * Retrieve category description. 
     314 * 
     315 * @since 1.0.0 
     316 * 
     317 * @param int $category Optional. Category ID. Will use global category ID by default. 
     318 * @return string Category description, available. 
     319 */ 
    211320function category_description( $category = 0 ) { 
    212321        global $cat; 
    213322        if ( !$category ) 
    … …  
    216325        return get_term_field( 'description', $category, 'category' ); 
    217326} 
    218327 
     328/** 
     329 * Display or retrieve the HTML dropdown list of categories. 
     330 * 
     331 * The list of arguments is below: 
     332 *     'show_option_all' (string) - Text to display for showing all categories. 
     333 *     'show_option_none' (string) - Text to display for showing no categories. 
     334 *     'orderby' (string) default is 'ID' - What column to use for ordering the 
     335 * categories. 
     336 *     'order' (string) default is 'ASC' - What direction to order categories. 
     337 *     'show_last_update' (bool|int) default is 0 - See {@link get_categories()} 
     338 *     'show_count' (bool|int) default is 0 - Whether to show how many posts are 
     339 * in the category. 
     340 *     'hide_empty' (bool|int) default is 1 - Whether to hide categories that 
     341 * don't have any posts attached to them. 
     342 *     'child_of' (int) default is 0 - See {@link get_categories()}. 
     343 *     'exclude' (string) - See {@link get_categories()}. 
     344 *     'echo' (bool|int) default is 1 - Whether to display or retrieve content. 
     345 *     'depth' (int) - The max depth. 
     346 *     'tab_index' (int) - Tab index for select element. 
     347 *     'name' (string) - The name attribute value for selected element. 
     348 *     'class' (string) - The class attribute value for selected element. 
     349 *     'selected' (int) - Which category ID is selected. 
     350 * 
     351 * The 'hierarchical' argument, which is disabled by default, will override the 
     352 * depth argument, unless it is true. When the argument is false, it will 
     353 * display all of the categories. When it is enabled it will use the value in 
     354 * the 'depth' argument. 
     355 * 
     356 * @since 2.1.0 
     357 * 
     358 * @param string|array $args Optional. Override default arguments. 
     359 * @return string HTML content only if 'echo' argument is 0. 
     360 */ 
    219361function wp_dropdown_categories( $args = '' ) { 
    220362        $defaults = array( 
    221363                'show_option_all' => '', 'show_option_none' => '', 
    … …  
    271413        return $output; 
    272414} 
    273415 
     416/** 
     417 * Display or retrieve the HTML list of categories. 
     418 * 
     419 * The list of arguments is below: 
     420 *     'show_option_all' (string) - Text to display for showing all categories. 
     421 *     'orderby' (string) default is 'ID' - What column to use for ordering the 
     422 * categories. 
     423 *     'order' (string) default is 'ASC' - What direction to order categories. 
     424 *     'show_last_update' (bool|int) default is 0 - See {@link  
     425 * walk_category_dropdown_tree()} 
     426 *     'show_count' (bool|int) default is 0 - Whether to show how many posts are 
     427 * in the category. 
     428 *     'hide_empty' (bool|int) default is 1 - Whether to hide categories that 
     429 * don't have any posts attached to them. 
     430 *     'use_desc_for_title' (bool|int) default is 1 - Whether to use the 
     431 * description instead of the category title. 
     432 *     'feed' - See {@link get_categories()}. 
     433 *     'feed_type' - See {@link get_categories()}. 
     434 *     'feed_image' - See {@link get_categories()}. 
     435 *     'child_of' (int) default is 0 - See {@link get_categories()}. 
     436 *     'exclude' (string) - See {@link get_categories()}. 
     437 *     'echo' (bool|int) default is 1 - Whether to display or retrieve content. 
     438 *     'current_category' (int) - See {@link get_categories()}. 
     439 *     'hierarchical' (bool) - See {@link get_categories()}. 
     440 *     'title_li' (string) - See {@link get_categories()}. 
     441 *     'depth' (int) - The max depth. 
     442 * 
     443 * @since 2.1.0 
     444 * 
     445 * @param string|array $args Optional. Override default arguments. 
     446 * @return string HTML content only if 'echo' argument is 0. 
     447 */ 
    274448function wp_list_categories( $args = '' ) { 
    275449        $defaults = array( 
    276450                'show_option_all' => '', 'orderby' => 'name', 
    … …  
    337511                return $output; 
    338512} 
    339513 
     514/** 
     515 * Display tag cloud. 
     516 * 
     517 * The text size is set by the 'smallest' and 'largest' arguments, which will 
     518 * use the 'unit' argument value for the CSS text size unit. The 'format' 
     519 * argument can be 'flat' (default), 'list', or 'array'. The flat value for the 
     520 * 'format' argument will separate tags with spaces. The list value for the 
     521 * 'format' argument will format the tags in a UL HTML list. The array value for 
     522 * the 'format' argument will return in PHP array type format. 
     523 * 
     524 * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'. 
     525 * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC'. 
     526 * 
     527 * The 'number' argument is how many tags to return. By default, the limit will 
     528 * be to return the top 45 tags in the tag cloud list. 
     529 * 
     530 * The 'single_text' and 'multiple_text' arguments are used for the link title 
     531 * for the tag link. If the tag only has one, it will use the text in the 
     532 * 'single_text' or if it has more than one it will use 'multiple_text' instead. 
     533 * 
     534 * The 'exclude' and 'include' arguments are used for the {@link get_tags()} 
     535 * function. Only one should be used, because only one will be used and the 
     536 * other ignored, if they are both set. 
     537 * 
     538 * @since 2.3.0 
     539 * 
     540 * @param array|string $args Optional. Override default arguments. 
     541 * @return array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument. 
     542 */ 
    340543function wp_tag_cloud( $args = '' ) { 
    341544        $defaults = array( 
    342545                'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 45, 
    … …  
    370573} 
    371574 
    372575/** 
    373  * Generates a tag cloud (heatmap) from provided data 
     576 * Generates a tag cloud (heatmap) from provided data. 
    374577 * 
    375  * TODO: Complete 
     578 * The text size is set by the 'smallest' and 'largest' arguments, which will 
     579 * use the 'unit' argument value for the CSS text size unit. The 'format' 
     580 * argument can be 'flat' (default), 'list', or 'array'. The flat value for the 
     581 * 'format' argument will separate tags with spaces. The list value for the 
     582 * 'format' argument will format the tags in a UL HTML list. The array value for 
     583 * the 'format' argument will return in PHP array type format. 
    376584 * 
    377  * @since 2.6 
     585 * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'. 
     586 * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC' or 
     587 * 'RAND'. 
    378588 * 
    379  * $tags = array of objects with the properties 'name', 'link', 'id', and 'count' 
    380  * $args['format'] = 'flat' => whitespace separated, 'list' => UL, 'array' => array() 
    381  * $args['orderby'] = 'name', 'count' 
    382 */ 
     589 * The 'number' argument is how many tags to return. By default, the limit will 
     590 * be to return the entire tag cloud list. 
     591 * 
     592 * The 'single_text' and 'multiple_text' arguments are used for the link title 
     593 * for the tag link. If the tag only has one, it will use the text in the 
     594 * 'single_text' or if it has more than one it will use 'multiple_text' instead. 
     595 * 
     596 * @todo Complete functionality. 
     597 * @since 2.3.0 
     598 * 
     599 * @param array $tags List of tags. 
     600 * @param string|array $args Optional, override default arguments. 
     601 * @return string 
     602 */ 
    383603function wp_generate_tag_cloud( $tags, $args = '' ) { 
    384604        global $wp_rewrite; 
    385605        $defaults = array( 
    … …  
    460680// Helper functions 
    461681// 
    462682 
     683/** 
     684 * Retrieve HTML list content for category list. 
     685 * 
     686 * @uses Walker_Category to create HTML list content. 
     687 * @since 2.1.0 
     688 * @see Walker_Category::walk() for parameters and return description. 
     689 */ 
    463690function walk_category_tree() { 
    464691        $walker = new Walker_Category; 
    465692        $args = func_get_args(); 
    466693        return call_user_func_array(array( &$walker, 'walk' ), $args ); 
    467694} 
    468695 
     696/** 
     697 * Retrieve HTML dropdown (select) content for category list. 
     698 * 
     699 * @uses Walker_CategoryDropdown to create HTML dropdown content. 
     700 * @since 2.1.0 
     701 * @see Walker_CategoryDropdown::walk() for parameters and return description. 
     702 */ 
    469703function walk_category_dropdown_tree() { 
    470704        $walker = new Walker_CategoryDropdown; 
    471705        $args = func_get_args(); 
    … …  
    476710// Tags 
    477711// 
    478712 
     713/** 
     714 * Retrieve the link to the tag. 
     715 * 
     716 * @since 2.3.0 
     717 * @uses apply_filters() Calls 'tag_link' with tag link and tag ID as parameters. 
     718 * 
     719 * @param int $tag_id Tag (term) ID. 
     720 * @return string 
     721 */ 
    479722function get_tag_link( $tag_id ) { 
    480723        global $wp_rewrite; 
    481724        $taglink = $wp_rewrite->get_tag_permastruct(); 
    … …  
    495738        return apply_filters( 'tag_link', $taglink, $tag_id ); 
    496739} 
    497740 
     741/** 
     742 * Retrieve the tags for a post. 
     743 * 
     744 * @since 2.3.0 
     745 * @uses apply_filters() Calls 'get_the_tags' filter on the list of post tags. 
     746 * 
     747 * @param int $id Post ID. 
     748 * @return array 
     749 */ 
    498750function get_the_tags( $id = 0 ) { 
    499751        return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) ); 
    500752} 
    501753 
     754/** 
     755 * Retrieve the tags for a post formatted as a string. 
     756 * 
     757 * @since 2.3.0 
     758 * @uses apply_filters() Calls 'the_tags' filter on string list of tags. 
     759 * 
     760 * @param string $before Optional. Before tags. 
     761 * @param string $sep Optional. Between tags. 
     762 * @param string $after Optional. After tags. 
     763 * @return string 
     764 */ 
    502765function get_the_tag_list( $before = '', $sep = '', $after = '' ) { 
    503766        return apply_filters( 'the_tags', get_the_term_list( 0, 'post_tag', $before, $sep, $after ) ); 
    504767} 
    505768 
     769/** 
     770 * Retrieve the tags for a post. 
     771 * 
     772 * @since 2.3.0 
     773 * 
     774 * @param string $before Optional. Before list. 
     775 * @param string $sep Optional. Separate items using this. 
     776 * @param string $after Optional. After list. 
     777 * @return string 
     778 */ 
    506779function the_tags( $before = 'Tags: ', $sep = ', ', $after = '' ) { 
    507780        return the_terms( 0, 'post_tag', $before, $sep, $after ); 
    508781} 
    509782 
     783/** 
     784 * Retrieve the terms of the taxonomy that are attached to the post. 
     785 * 
     786 * This function can only be used within the loop. 
     787 * 
     788 * @since 2.5.0 
     789 * 
     790 * @param int $id Post ID. Is not optional. 
     791 * @param string $taxonomy Taxonomy name. 
     792 * @return array|bool False on failure. Array of term objects on success. 
     793 */ 
    510794function get_the_terms( $id = 0, $taxonomy ) { 
    511795        global $post; 
    512796 
    … …  
    528812        return $terms; 
    529813} 
    530814 
     815/** 
     816 * Retrieve terms as a list with specified format. 
     817 * 
     818 * @since 2.5.0 
     819 * 
     820 * @param int $id Term ID. 
     821 * @param string $taxonomy Taxonomy name. 
     822 * @param string $before Optional. Before list. 
     823 * @param string $sep Optional. Separate items using this. 
     824 * @param string $after Optional. After list. 
     825 * @return string 
     826 */ 
    531827function get_the_term_list( $id = 0, $taxonomy, $before = '', $sep = '', $after = '' ) { 
    532828        $terms = get_the_terms( $id, $taxonomy ); 
    533829 
    … …  
    549845        return $before . join( $sep, $term_links ) . $after; 
    550846} 
    551847 
     848/** 
     849 * Display the terms in a list. 
     850 * 
     851 * @since 2.5.0 
     852 * 
     853 * @param int $id Term ID. 
     854 * @param string $taxonomy Taxonomy name. 
     855 * @param string $before Optional. Before list. 
     856 * @param string $sep Optional. Separate items using this. 
     857 * @param string $after Optional. After list. 
     858 * @return null|bool False on WordPress error. Returns null when displaying. 
     859 */ 
    552860function the_terms( $id, $taxonomy, $before = '', $sep = '', $after = '' ) { 
    553861        $return = get_the_term_list( $id, $taxonomy, $before, $sep, $after ); 
    554862        if ( is_wp_error( $return ) ) 
    … …  
    558866} 
    559867 
    560868/** 
    561  * Check if the current post has the given tag 
     869 * Check if the current post has the given tag. 
    562870 * 
    563  * @package WordPress 
    564  * @since 2.6 
     871 * This function is only for use within the WordPress Loop. 
    565872 * 
     873 * @since 2.6.0 
     874 * 
    566875 * @uses wp_get_object_terms() Gets the tags. 
    567876 * 
    568  * @param string|int|array $tag Optional. The tag name/id/slug or array of them to check for 
    569  * @return bool True if the current post has the given tag, or any tag, if no tag specified 
     877 * @param string|int|array $tag Optional. The tag name/id/slug or array of them to check for. 
     878 * @return bool True if the current post has the given tag, or any tag, if no tag specified. 
    570879 */ 
    571880function has_tag( $tag = '' ) { 
    572881        global $post;