WordPress.org
Get WordPress

Make WordPress Core

Ticket #5642: 5642.r9247.diff

File 5642.r9247.diff, 22.5 KB (added by jacobsantos, 17 years ago)

Completed link-template.php file based off of r9247

  • link-template.php

     
    77 */
    88
    99/**
    10  * {@internal Missing Short Description}}
     10 * Display the permalink for the current post.
    1111 *
    12  * {@internal Missing Long Description}}
    13  *
    1412 * @since 1.2.0
    15  * @uses apply_filters()
     13 * @uses apply_filters() Calls 'the_permalink' filter on the permalink string.
    1614 */
    1715function the_permalink() {
    1816        echo apply_filters('the_permalink', get_permalink());
    1917}
    2018
    2119/**
    22  * {@internal Missing Short Description}}
     20 * Retrieve trailing slash string, if blog set for adding trailing slashes.
    2321 *
    24  * Conditionally adds a trailing slash if the permalink structure
    25  * has a trailing slash, strips the trailing slash if not
    26  * {@internal Missing Long Description}}
     22 * Conditionally adds a trailing slash if the permalink structure has a trailing
     23 * slash, strips the trailing slash if not. The string is passed through the
     24 * 'user_trailingslashit' filter. Will remove trailing slash from string, if
     25 * blog is not set to have them.
    2726 *
    2827 * @since 2.2.0
    2928 * @uses $wp_rewrite
    3029 *
    31  * @param $string String a URL with or without a trailing slash
    32  * @param $type_of_url String the type of URL being considered (e.g. single, category, etc) for use in the filter
     30 * @param $string String a URL with or without a trailing slash.
     31 * @param $type_of_url String the type of URL being considered (e.g. single, category, etc) for use in the filter.
    3332 * @return string
    3433 */
    3534function user_trailingslashit($string, $type_of_url = '') {
    … …  
    4645}
    4746
    4847/**
    49  * {@internal Missing Short Description}}
     48 * Display permalink anchor for current post.
    5049 *
    51  * {@internal Missing Long Description}}
     50 * The permalink mode title will use the post title for the 'a' element 'id'
     51 * attribute. The id mode uses 'post-' with the post ID for the 'id' attribute.
    5252 *
    5353 * @since 0.71
    5454 *
    55  * @param unknown_type $mode
     55 * @param string $mode Permalink mode can be either 'title', 'id', or default, which is 'id'.
    5656 */
    5757function permalink_anchor($mode = 'id') {
    5858        global $post;
    … …  
    6969}
    7070
    7171/**
    72  * {@internal Missing Short Description}}
     72 * Retrieve full permalink for current post or post ID.
    7373 *
    74  * {@internal Missing Long Description}}
    75  *
    7674 * @since 1.0.0
    7775 *
    78  * @param unknown_type $id
    79  * @return unknown
     76 * @param int $id Optional. Post ID.
     77 * @param bool $leavename Optional, defaults to false. Whether to keep post name or page name.
     78 * @return string
    8079 */
    81 function get_permalink($id = 0, $leavename=false) {
     80function get_permalink($id = 0, $leavename = false) {
    8281        $rewritecode = array(
    8382                '%year%',
    8483                '%monthnum%',
    … …  
    9594
    9695        $post = &get_post($id);
    9796
    98         if ( empty($post->ID) ) return FALSE;
     97        if ( empty($post->ID) ) return false;
    9998
    10099        if ( $post->post_type == 'page' )
    101100                return get_page_link($post->ID, $leavename);
    … …  
    114113                                usort($cats, '_usort_terms_by_ID'); // order by ID
    115114                        $category = $cats[0]->slug;
    116115                        if ( $parent=$cats[0]->parent )
    117                                 $category = get_category_parents($parent, FALSE, '/', TRUE) . $category;
     116                                $category = get_category_parents($parent, false, '/', true) . $category;
    118117
    119118                        // show default category in permalinks, without
    120119                        // having to assign it explicitly
    … …  
    157156/**
    158157 * Retrieve permalink from post ID.
    159158 *
    160  * {@internal Missing Long Description}}
    161  *
    162159 * @since 1.0.0
    163160 *
    164  * @param unknown_type $post_id
    165  * @param unknown_type $deprecated
    166  * @return unknown
     161 * @param int $post_id Optional. Post ID.
     162 * @param mixed $deprecated Not used.
     163 * @return string
    167164 */
    168165function post_permalink($post_id = 0, $deprecated = '') {
    169166        return get_permalink($post_id);
    170167}
    171168
    172 // Respects page_on_front.  Use this one.
    173169/**
    174  * {@internal Missing Short Description}}
     170 * Retrieve the permalink for current page or page ID.
    175171 *
    176  * {@internal Missing Long Description}}
     172 * Respects page_on_front. Use this one.
    177173 *
    178174 * @since 1.5.0
    179175 *
    180  * @param unknown_type $id
    181  * @return unknown
     176 * @param int $id Optional. Post ID.
     177 * @param bool $leavename Optional, defaults to false. Whether to keep post name or page name.
     178 * @return string
    182179 */
    183180function get_page_link($id = false, $leavename = false) {
    184181        global $post;
    … …  
    196193}
    197194
    198195/**
    199  * {@internal Missing Short Description}}
     196 * Retrieve the page permalink.
    200197 *
    201  * {@internal Missing Long Description}}
    202  *
    203198 * Ignores page_on_front. Internal use only.
    204199 *
    205200 * @since 2.1.0
    206201 * @access private
    207202 *
    208  * @param unknown_type $id
    209  * @return unknown
     203 * @param int $id Optional. Post ID.
     204 * @param bool $leavename Optional. Leave name.
     205 * @return string
    210206 */
    211207function _get_page_link( $id = false, $leavename = false ) {
    212208        global $post, $wp_rewrite;
    … …  
    231227}
    232228
    233229/**
    234  * {@internal Missing Short Description}}
     230 * Retrieve permalink for attachment.
    235231 *
    236  * {@internal Missing Long Description}}
     232 * This can be used in the WordPress Loop or outside of it.
    237233 *
    238234 * @since 2.0.0
    239235 *
    240  * @param unknown_type $id
    241  * @return unknown
     236 * @param int $id Optional. Post ID.
     237 * @return string
    242238 */
    243239function get_attachment_link($id = false) {
    244240        global $post, $wp_rewrite;
    … …  
    272268}
    273269
    274270/**
    275  * {@internal Missing Short Description}}
     271 * Retrieve the permalink for the year archives.
    276272 *
    277  * {@internal Missing Long Description}}
    278  *
    279273 * @since 1.5.0
    280274 *
    281  * @param unknown_type $year
    282  * @return unknown
     275 * @param int|bool $year False for current year or year for permalink.
     276 * @return string
    283277 */
    284278function get_year_link($year) {
    285279        global $wp_rewrite;
    … …  
    295289}
    296290
    297291/**
    298  * {@internal Missing Short Description}}
     292 * Retrieve the permalink for the month archives with year.
    299293 *
    300  * {@internal Missing Long Description}}
    301  *
    302294 * @since 1.0.0
    303295 *
    304  * @param unknown_type $year
    305  * @param unknown_type $month
    306  * @return unknown
     296 * @param bool|int $year False for current year. Integer of year.
     297 * @param bool|int $month False for current month. Integer of month.
     298 * @return string
    307299 */
    308300function get_month_link($year, $month) {
    309301        global $wp_rewrite;
    … …  
    322314}
    323315
    324316/**
    325  * {@internal Missing Short Description}}
     317 * Retrieve the permalink for the day archives with year and month.
    326318 *
    327  * {@internal Missing Long Description}}
    328  *
    329319 * @since 1.0.0
    330320 *
    331  * @param unknown_type $year
    332  * @param unknown_type $month
    333  * @param unknown_type $day
    334  * @return unknown
     321 * @param bool|int $year False for current year. Integer of year.
     322 * @param bool|int $month False for current month. Integer of month.
     323 * @param bool|int $day False for current day. Integer of day.
     324 * @return string
    335325 */
    336326function get_day_link($year, $month, $day) {
    337327        global $wp_rewrite;
    … …  
    354344}
    355345
    356346/**
    357  * {@internal Missing Short Description}}
     347 * Retrieve the permalink for the feed type.
    358348 *
    359  * {@internal Missing Long Description}}
    360  *
    361349 * @since 1.5.0
    362350 *
    363  * @param unknown_type $feed
    364  * @return unknown
     351 * @param string $feed Optional, defaults to default feed. Feed type.
     352 * @return string
    365353 */
    366354function get_feed_link($feed = '') {
    367355        global $wp_rewrite;
    … …  
    393381}
    394382
    395383/**
    396  * {@internal Missing Short Description}}
     384 * Retrieve the permalink for the post comments feed.
    397385 *
    398  * {@internal Missing Long Description}}
    399  *
    400386 * @since 2.2.0
    401387 *
    402  * @param unknown_type $post_id
    403  * @param unknown_type $feed
    404  * @return unknown
     388 * @param int $post_id Optional. Post ID.
     389 * @param string $feed Optional. Feed type.
     390 * @return string
    405391 */
    406392function get_post_comments_feed_link($post_id = '', $feed = '') {
    407393        global $id;
    … …  
    463449 * @since 2.5.0
    464450 *
    465451 * @param int $author_id ID of an author.
    466  * @param string $feed Feed type.
     452 * @param string $feed Optional. Feed type.
    467453 * @return string Link to the feed for the author specified by $author_id.
    468454*/
    469455function get_author_feed_link( $author_id, $feed = '' ) {
    … …  
    501487 * @since 2.5.0
    502488 *
    503489 * @param int $cat_id ID of a category.
    504  * @param string $feed Feed type.
     490 * @param string $feed Optional. Feed type.
    505491 * @return string Link to the feed for the category specified by $cat_id.
    506492*/
    507493function get_category_feed_link($cat_id, $feed = '') {
    … …  
    535521}
    536522
    537523/**
    538  * {@internal Missing Short Description}}
     524 * Retrieve permalink for feed of tag.
    539525 *
    540  * {@internal Missing Long Description}}
    541  *
    542526 * @since 2.3.0
    543527 *
    544  * @param unknown_type $tag_id
    545  * @param unknown_type $feed
    546  * @return unknown
     528 * @param int $tag_id Tag ID.
     529 * @param string $feed Optional. Feed type.
     530 * @return string
    547531 */
    548532function get_tag_feed_link($tag_id, $feed = '') {
    549533        $tag_id = (int) $tag_id;
    … …  
    575559}
    576560
    577561/**
    578  * {@internal Missing Short Description}}
     562 * Retrieve the permalink for the feed of the search results.
    579563 *
    580  * {@internal Missing Long Description}}
    581  *
    582564 * @since 2.5.0
    583565 *
    584  * @param unknown_type $search_query
    585  * @param unknown_type $feed
    586  * @return unknown
     566 * @param string $search_query Optional. Search query.
     567 * @param string $feed Optional. Feed type.
     568 * @return string
    587569 */
    588570function get_search_feed_link($search_query = '', $feed = '') {
    589571        if ( empty($search_query) )
    … …  
    602584}
    603585
    604586/**
    605  * {@internal Missing Short Description}}
     587 * Retrieve the permalink for the comments feed of the search results.
    606588 *
    607  * {@internal Missing Long Description}}
    608  *
    609589 * @since 2.5.0
    610590 *
    611  * @param unknown_type $search_query
    612  * @param unknown_type $feed
    613  * @return unknown
     591 * @param string $search_query Optional. Search query.
     592 * @param string $feed Optional. Feed type.
     593 * @return string
    614594 */
    615595function get_search_comments_feed_link($search_query = '', $feed = '') {
    616596        if ( empty($search_query) )
    … …  
    629609}
    630610
    631611/**
    632  * {@internal Missing Short Description}}
     612 * Retrieve edit posts link for post.
    633613 *
    634  * {@internal Missing Long Description}}
     614 * Can be used within the WordPress loop or outside of it. Can be used with
     615 * pages, posts, attachments, and revisions.
    635616 *
    636617 * @since 2.3.0
    637618 *
    638  * @param unknown_type $id
    639  * @return unknown
     619 * @param int $id Optional. Post ID.
     620 * @param string $context Optional, default to display. How to write the '&', defaults to '&'.
     621 * @return string
    640622 */
    641623function get_edit_post_link( $id = 0, $context = 'display' ) {
    642624        if ( !$post = &get_post( $id ) )
    … …  
    679661}
    680662
    681663/**
    682  * {@internal Missing Short Description}}
     664 * Retrieve edit posts link for post.
    683665 *
    684  * {@internal Missing Long Description}}
    685  *
    686666 * @since 1.0.0
    687667 *
    688  * @param unknown_type $link
    689  * @param unknown_type $before
    690  * @param unknown_type $after
     668 * @param string $link Optional. Anchor text.
     669 * @param string $before Optional. Display before edit link.
     670 * @param string $after Optional. Display after edit link.
    691671 */
    692672function edit_post_link( $link = 'Edit This', $before = '', $after = '' ) {
    693673        global $post;
    … …  
    705685}
    706686
    707687/**
    708  * {@internal Missing Short Description}}
     688 * Retrieve edit comment link.
    709689 *
    710  * {@internal Missing Long Description}}
    711  *
    712690 * @since 2.3.0
    713691 *
    714  * @param unknown_type $comment_id
    715  * @return unknown
     692 * @param int $comment_id Optional. Comment ID.
     693 * @return string
    716694 */
    717695function get_edit_comment_link( $comment_id = 0 ) {
    718696        $comment = &get_comment( $comment_id );
    … …  
    731709}
    732710
    733711/**
    734  * {@internal Missing Short Description}}
     712 * Display or retrieve edit comment link with formatting.
    735713 *
    736  * {@internal Missing Long Description}}
    737  *
    738714 * @since 1.0.0
    739715 *
    740  * @param unknown_type $link
    741  * @param unknown_type $before
    742  * @param unknown_type $after
     716 * @param string $link Optional. Anchor text.
     717 * @param string $before Optional. Display before edit link.
     718 * @param string $after Optional. Display after edit link.
     719 * @param bool $echo Optional, defaults to true. Whether to echo or return HTML.
     720 * @return string|null HTML content, if $echo is set to false.
    743721 */
    744722function edit_comment_link( $link = 'Edit This', $before = '', $after = '', $echo = true ) {
    745723        global $comment, $post;
    … …  
    762740}
    763741
    764742/**
    765  * {@internal Missing Short Description}}
     743 * Display edit bookmark (literally a URL external to blog) link.
    766744 *
    767  * {@internal Missing Long Description}}
     745 * @since 2.7.0
    768746 *
    769  * @since unknown
    770  *
    771  * @param unknown_type $link
    772  * @return unknown
     747 * @param int $link Optional. Bookmark ID.
     748 * @return string
    773749 */
    774750function get_edit_bookmark_link( $link = 0 ) {
    775751        $link = &get_bookmark( $link );
    … …  
    782758}
    783759
    784760/**
    785  * {@internal Missing Short Description}}
     761 * Display edit bookmark (literally a URL external to blog) link anchor content.
    786762 *
    787  * {@internal Missing Long Description}}
     763 * @since 2.7.0
    788764 *
    789  * @since unknown
    790  *
    791  * @param unknown_type $link
    792  * @param unknown_type $before
    793  * @param unknown_type $after
    794  * @param unknown_type $bookmark
     765 * @param string $link Optional. Anchor text.
     766 * @param string $before Optional. Display before edit link.
     767 * @param string $after Optional. Display after edit link.
     768 * @param int $bookmark Optional. Bookmark ID.
    795769 */
    796770function edit_bookmark_link( $link = '', $before = '', $after = '', $bookmark = null ) {
    797771        $bookmark = get_bookmark($bookmark);
    … …  
    809783// Navigation links
    810784
    811785/**
    812  * {@internal Missing Short Description}}
     786 * Retrieve previous post link that is adjacent to current post.
    813787 *
    814  * {@internal Missing Long Description}}
    815  *
    816788 * @since 1.5.0
    817789 *
    818  * @param unknown_type $in_same_cat
    819  * @param unknown_type $excluded_categories
    820  * @return unknown
     790 * @param bool $in_same_cat Optional. Whether link should be in same category.
     791 * @param string $excluded_categories Optional. Excluded categories IDs.
     792 * @return string
    821793 */
    822794function get_previous_post($in_same_cat = false, $excluded_categories = '') {
    823795        return get_adjacent_post($in_same_cat, $excluded_categories);
    824796}
    825797
    826798/**
    827  * {@internal Missing Short Description}}
     799 * Retrieve next post link that is adjacent to current post.
    828800 *
    829  * {@internal Missing Long Description}}
    830  *
    831801 * @since 1.5.0
    832802 *
    833  * @param unknown_type $in_same_cat
    834  * @param unknown_type $excluded_categories
    835  * @return unknown
     803 * @param bool $in_same_cat Optional. Whether link should be in same category.
     804 * @param string $excluded_categories Optional. Excluded categories IDs.
     805 * @return string
    836806 */
    837807function get_next_post($in_same_cat = false, $excluded_categories = '') {
    838808        return get_adjacent_post($in_same_cat, $excluded_categories, false);
    839809}
    840810
    841811/**
    842  * {@internal Missing Short Description}}
     812 * Retrieve adjacent post link.
    843813 *
    844  * {@internal Missing Long Description}}
     814 * Can either be next or previous post link.
    845815 *
    846816 * @since 2.5.0
    847817 *
    848  * @param unknown_type $in_same_cat
    849  * @param unknown_type $excluded_categories
    850  * @param unknown_type $previous
    851  * @return unknown
     818 * @param bool $in_same_cat Optional. Whether link should be in same category.
     819 * @param string $excluded_categories Optional. Excluded categories IDs.
     820 * @param bool $previous Optional. Whether to retrieve previous post.
     821 * @return string
    852822 */
    853823function get_adjacent_post($in_same_cat = false, $excluded_categories = '', $previous = true) {
    854824        global $post, $wpdb;
    … …  
    894864}
    895865
    896866/**
    897  * {@internal Missing Short Description}}
     867 * Display previous post link that is adjacent to the current post.
    898868 *
    899  * {@internal Missing Long Description}}
    900  *
    901869 * @since 1.5.0
    902870 *
    903  * @param unknown_type $format
    904  * @param unknown_type $link
    905  * @param unknown_type $in_same_cat
    906  * @param unknown_type $excluded_categories
     871 * @param string $format Optional. Link anchor format.
     872 * @param string $link Optional. Link permalink format.
     873 * @param bool $in_same_cat Optional. Whether link should be in same category.
     874 * @param string $excluded_categories Optional. Excluded categories IDs.
    907875 */
    908876function previous_post_link($format='« %link', $link='%title', $in_same_cat = false, $excluded_categories = '') {
    909877        adjacent_post_link($format, $link, $in_same_cat, $excluded_categories, true);
    910878}
    911879
    912880/**
    913  * {@internal Missing Short Description}}
     881 * Display next post link that is adjacent to the current post.
    914882 *
    915  * {@internal Missing Long Description}}
    916  *
    917883 * @since 1.5.0
    918884 *
    919  * @param unknown_type $format
    920  * @param unknown_type $link
    921  * @param unknown_type $in_same_cat
    922  * @param unknown_type $excluded_categories
     885 * @param string $format Optional. Link anchor format.
     886 * @param string $link Optional. Link permalink format.
     887 * @param bool $in_same_cat Optional. Whether link should be in same category.
     888 * @param string $excluded_categories Optional. Excluded categories IDs.
    923889 */
    924890function next_post_link($format='%link »', $link='%title', $in_same_cat = false, $excluded_categories = '') {
    925891        adjacent_post_link($format, $link, $in_same_cat, $excluded_categories, false);
    926892}
    927893
    928894/**
    929  * {@internal Missing Short Description}}
     895 * Display adjacent post link.
    930896 *
    931  * {@internal Missing Long Description}}
     897 * Can be either next post link or previous.
    932898 *
    933899 * @since 2.5.0
    934900 *
    935  * @param unknown_type $format
    936  * @param unknown_type $link
    937  * @param unknown_type $in_same_cat
    938  * @param unknown_type $excluded_categories
    939  * @param unknown_type $previous
     901 * @param string $format Link anchor format.
     902 * @param string $link Link permalink format.
     903 * @param bool $in_same_cat Optional. Whether link should be in same category.
     904 * @param string $excluded_categories Optional. Excluded categories IDs.
     905 * @param bool $previous Optional, default is true. Whether display link to previous post.
    940906 */
    941907function adjacent_post_link($format, $link, $in_same_cat = false, $excluded_categories = '', $previous = true) {
    942908        if ( $previous && is_attachment() )
    … …  
    967933}
    968934
    969935/**
    970  * {@internal Missing Short Description}}
     936 * Retrieve get links for page numbers.
    971937 *
    972  * {@internal Missing Long Description}}
    973  *
    974938 * @since 1.5.0
    975939 *
    976  * @param unknown_type $pagenum
    977  * @return unknown
     940 * @param int $pagenum Optional. Page ID.
     941 * @return string
    978942 */
    979943function get_pagenum_link($pagenum = 1) {
    980944        global $wp_rewrite;
    … …  
    1031995}
    1032996
    1033997/**
    1034  * {@internal Missing Short Description}}
     998 * Retrieve next posts pages link.
    1035999 *
    1036  * {@internal Missing Long Description}}
    10371000 * Backported from 2.1.3 to 2.0.10.
    10381001 *
    10391002 * @since 2.0.10
    10401003 *
    1041  * @param unknown_type $max_page
    1042  * @return unknown
     1004 * @param int $max_page Optional. Max pages.
     1005 * @return string
    10431006 */
    10441007function get_next_posts_page_link($max_page = 0) {
    10451008        global $paged;
    … …  
    10541017}
    10551018
    10561019/**
    1057  * {@internal Missing Short Description}}
     1020 * Display the next posts pages link.
    10581021 *
    1059  * {@internal Missing Long Description}}
    1060  *
    10611022 * @since 0.71
    10621023 *
    1063  * @param unknown_type $max_page
     1024 * @param int $max_page Optional. Max pages.
    10641025 */
    10651026function next_posts($max_page = 0) {
    10661027        echo clean_url(get_next_posts_page_link($max_page));
    10671028}
    10681029
    10691030/**
    1070  * {@internal Missing Short Description}}
     1031 * Display the next posts pages link.
    10711032 *
    1072  * {@internal Missing Long Description}}
    1073  *
    10741033 * @since 0.71
    10751034 *
    1076  * @param unknown_type $label
    1077  * @param unknown_type $max_page
     1035 * @param string $label Content for link text.
     1036 * @param int $max_page Optional. Max pages.
    10781037 */
    10791038function next_posts_link($label='Next Page »', $max_page=0) {
    10801039        global $paged, $wp_query;
    … …  
    10931052}
    10941053
    10951054/**
    1096  * {@internal Missing Short Description}}
     1055 * Retrieve previous post pages link.
    10971056 *
    1098  * {@internal Missing Long Description}}
     1057 * Will only return string, if not on a single page or post.
    10991058 *
    1100  * @since 2.0.10 Backported
    1101  * @since 2.1.3
     1059 * Backported to 2.0.10 from 2.1.3.
    11021060 *
    1103  * @return unknown
     1061 * @since 2.0.10
     1062 *
     1063 * @return string|null
    11041064 */
    11051065function get_previous_posts_page_link() {
    11061066        global $paged;
    … …  
    11141074}
    11151075
    11161076/**
    1117  * {@internal Missing Short Description}}
     1077 * Display previous posts pages link.
    11181078 *
    1119  * {@internal Missing Long Description}}
    1120  *
    11211079 * @since 0.71
    1122  *
    11231080 */
    11241081function previous_posts() {
    11251082        echo clean_url(get_previous_posts_page_link());
    11261083}
    11271084
    11281085/**
    1129  * {@internal Missing Short Description}}
     1086 * Display previous posts page link.
    11301087 *
    1131  * {@internal Missing Long Description}}
    1132  *
    11331088 * @since 0.71
    11341089 *
    1135  * @param unknown_type $label
     1090 * @param string $label Optional. Previous page link text.
    11361091 */
    11371092function previous_posts_link($label='« Previous Page') {
    11381093        global $paged;
    … …  
    11451100}
    11461101
    11471102/**
    1148  * {@internal Missing Short Description}}
     1103 * Display post pages link navigation for previous and next pages.
    11491104 *
    1150  * {@internal Missing Long Description}}
    1151  *
    11521105 * @since 0.71
    11531106 *
    1154  * @param unknown_type $sep
    1155  * @param unknown_type $prelabel
    1156  * @param unknown_type $nxtlabel
     1107 * @param string $sep Optional. Separator for posts navigation links.
     1108 * @param string $prelabel Optional. Label for previous pages.
     1109 * @param string $nxtlabel Optional Label for next pages.
    11571110 */
    11581111function posts_nav_link($sep=' — ', $prelabel='« Previous Page', $nxtlabel='Next Page »') {
    11591112        global $wp_query;
    … …  
    11741127        }
    11751128}
    11761129
     1130/**
     1131 * Retrieve page numbers links.
     1132 *
     1133 * @since 2.7.0
     1134 *
     1135 * @param int $pagenum Optional. Page number.
     1136 * @return string
     1137 */
    11771138function get_comments_pagenum_link($pagenum = 1) {
    11781139        global $wp_rewrite;
    11791140
    … …  
    12031164        return $result;
    12041165}
    12051166
     1167/**
     1168 * Display link to next comments pages.
     1169 *
     1170 * @since 2.7.0
     1171 *
     1172 * @param string $label Optional. Label for link text.
     1173 * @param int $max_page Optional. Max page.
     1174 */
    12061175function next_comments_link($label='', $max_page = 0) {
    12071176        global $wp_query;
    12081177
    … …  
    12301199        echo "\" $attr>". preg_replace('/&([^#])(?![a-z]{1,8};)/', '&#038;$1', $label) .'</a>';
    12311200}
    12321201
     1202/**
     1203 * Display the previous comments page link.
     1204 *
     1205 * @since 2.7.0
     1206 *
     1207 * @param string $label Optional. Label for comments link text.
     1208 */
    12331209function previous_comments_link($label='') {
    12341210        global $wp_query;
    12351211
    … …  
    12541230        echo "\" $attr>". preg_replace('/&([^#])(?![a-z]{1,8};)/', '&#038;$1', $label) .'</a>';
    12551231}
    12561232
    1257 /** Create pagination links for the comments on the current post
     1233/**
     1234 * Create pagination links for the comments on the current post.
    12581235 *
    1259  * @package WordPress
    1260  * @see paginate_links
    1261  * @since 2.7
     1236 * @see paginate_links()
     1237 * @since 2.7.0
    12621238 *
    12631239 * @param string|array $args Optional args. See paginate_links.
    1264  * @return string Markup for pagination links
     1240 * @return string Markup for pagination links.
    12651241*/
    12661242function paginate_comments_links($args = array()) {
    12671243        global $wp_query;
    … …  
    12911267}
    12921268
    12931269/**
    1294  * {@internal Missing Short Description}}
     1270 * Retrieve shortcut link.
    12951271 *
    1296  * {@internal Missing Long Description}}
     1272 * Use this in 'a' element 'href' attribute.
    12971273 *
    1298  * @since unknown
     1274 * @since 2.6.0
    12991275 *
    1300  * @return unknown
     1276 * @return string
    13011277 */
    13021278function get_shortcut_link() {
    13031279        $link = "javascript:
    … …  
    13351311 * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
    13361312 * overridden.
    13371313 *
     1314 * @package WordPress
    13381315 * @since 2.6.0
    13391316 *
    13401317 * @param string $path Optional. Path relative to the site url.