Make WordPress Core

Changeset 9274


Ignore:
Timestamp:
10/22/2008 03:08:33 AM (17 years ago)
Author:
ryan
Message:

link-template phpdoc from jacobsantos. fixes #5642

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/link-template.php

    r9243 r9274  
    88
    99/**
    10  * {@internal Missing Short Description}}
    11  *
    12  * {@internal Missing Long Description}}
     10 * Display the permalink for the current post.
    1311 *
    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() {
     
    2018
    2119/**
    22  * {@internal Missing Short Description}}
    23  *
    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}}
     20 * Retrieve trailing slash string, if blog set for adding trailing slashes.
     21 *
     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 */
     
    4746
    4847/**
    49  * {@internal Missing Short Description}}
    50  *
    51  * {@internal Missing Long Description}}
     48 * Display permalink anchor for current post.
     49 *
     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') {
     
    7070
    7171/**
    72  * {@internal Missing Short Description}}
    73  *
    74  * {@internal Missing Long Description}}
     72 * Retrieve full permalink for current post or post ID.
    7573 *
    7674 * @since 1.0.0
    7775 *
    78  * @param unknown_type $id
    79  * @return unknown
    80  */
    81 function get_permalink($id = 0, $leavename=false) {
     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
     79 */
     80function get_permalink($id = 0, $leavename = false) {
    8281    $rewritecode = array(
    8382        '%year%',
     
    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' )
     
    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
     
    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 = '') {
     
    170167}
    171168
    172 // Respects page_on_front.  Use this one.
    173 /**
    174  * {@internal Missing Short Description}}
    175  *
    176  * {@internal Missing Long Description}}
     169/**
     170 * Retrieve the permalink for current page or page ID.
     171 *
     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) {
     
    197194
    198195/**
    199  * {@internal Missing Short Description}}
    200  *
    201  * {@internal Missing Long Description}}
     196 * Retrieve the page permalink.
    202197 *
    203198 * Ignores page_on_front. Internal use only.
     
    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 ) {
     
    232228
    233229/**
    234  * {@internal Missing Short Description}}
    235  *
    236  * {@internal Missing Long Description}}
     230 * Retrieve permalink for attachment.
     231 *
     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) {
     
    273269
    274270/**
    275  * {@internal Missing Short Description}}
    276  *
    277  * {@internal Missing Long Description}}
     271 * Retrieve the permalink for the year archives.
    278272 *
    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) {
     
    296290
    297291/**
    298  * {@internal Missing Short Description}}
    299  *
    300  * {@internal Missing Long Description}}
     292 * Retrieve the permalink for the month archives with year.
    301293 *
    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) {
     
    323315
    324316/**
    325  * {@internal Missing Short Description}}
    326  *
    327  * {@internal Missing Long Description}}
     317 * Retrieve the permalink for the day archives with year and month.
    328318 *
    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) {
     
    355345
    356346/**
    357  * {@internal Missing Short Description}}
    358  *
    359  * {@internal Missing Long Description}}
     347 * Retrieve the permalink for the feed type.
    360348 *
    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 = '') {
     
    394382
    395383/**
    396  * {@internal Missing Short Description}}
    397  *
    398  * {@internal Missing Long Description}}
     384 * Retrieve the permalink for the post comments feed.
    399385 *
    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 = '') {
     
    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*/
     
    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*/
     
    536522
    537523/**
    538  * {@internal Missing Short Description}}
    539  *
    540  * {@internal Missing Long Description}}
     524 * Retrieve permalink for feed of tag.
    541525 *
    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 = '') {
     
    576560
    577561/**
    578  * {@internal Missing Short Description}}
    579  *
    580  * {@internal Missing Long Description}}
     562 * Retrieve the permalink for the feed of the search results.
    581563 *
    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 = '') {
     
    603585
    604586/**
    605  * {@internal Missing Short Description}}
    606  *
    607  * {@internal Missing Long Description}}
     587 * Retrieve the permalink for the comments feed of the search results.
    608588 *
    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 = '') {
     
    630610
    631611/**
    632  * {@internal Missing Short Description}}
    633  *
    634  * {@internal Missing Long Description}}
     612 * Retrieve edit posts link for post.
     613 *
     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' ) {
     
    680662
    681663/**
    682  * {@internal Missing Short Description}}
    683  *
    684  * {@internal Missing Long Description}}
     664 * Retrieve edit posts link for post.
    685665 *
    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 = '' ) {
     
    706686
    707687/**
    708  * {@internal Missing Short Description}}
    709  *
    710  * {@internal Missing Long Description}}
     688 * Retrieve edit comment link.
    711689 *
    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 ) {
     
    732710
    733711/**
    734  * {@internal Missing Short Description}}
    735  *
    736  * {@internal Missing Long Description}}
     712 * Display or retrieve edit comment link with formatting.
    737713 *
    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 ) {
     
    763741
    764742/**
    765  * {@internal Missing Short Description}}
    766  *
    767  * {@internal Missing Long Description}}
    768  *
    769  * @since unknown
    770  *
    771  * @param unknown_type $link
    772  * @return unknown
     743 * Display edit bookmark (literally a URL external to blog) link.
     744 *
     745 * @since 2.7.0
     746 *
     747 * @param int $link Optional. Bookmark ID.
     748 * @return string
    773749 */
    774750function get_edit_bookmark_link( $link = 0 ) {
     
    783759
    784760/**
    785  * {@internal Missing Short Description}}
    786  *
    787  * {@internal Missing Long Description}}
    788  *
    789  * @since unknown
    790  *
    791  * @param unknown_type $link
    792  * @param unknown_type $before
    793  * @param unknown_type $after
    794  * @param unknown_type $bookmark
     761 * Display edit bookmark (literally a URL external to blog) link anchor content.
     762 *
     763 * @since 2.7.0
     764 *
     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 ) {
     
    810784
    811785/**
    812  * {@internal Missing Short Description}}
    813  *
    814  * {@internal Missing Long Description}}
     786 * Retrieve previous post link that is adjacent to current post.
    815787 *
    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 = '') {
     
    825797
    826798/**
    827  * {@internal Missing Short Description}}
    828  *
    829  * {@internal Missing Long Description}}
     799 * Retrieve next post link that is adjacent to current post.
    830800 *
    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 = '') {
     
    840810
    841811/**
    842  * {@internal Missing Short Description}}
    843  *
    844  * {@internal Missing Long Description}}
     812 * Retrieve adjacent post link.
     813 *
     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) {
     
    895865
    896866/**
    897  * {@internal Missing Short Description}}
    898  *
    899  * {@internal Missing Long Description}}
     867 * Display previous post link that is adjacent to the current post.
    900868 *
    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 = '') {
     
    911879
    912880/**
    913  * {@internal Missing Short Description}}
    914  *
    915  * {@internal Missing Long Description}}
     881 * Display next post link that is adjacent to the current post.
    916882 *
    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 = '') {
     
    927893
    928894/**
    929  * {@internal Missing Short Description}}
    930  *
    931  * {@internal Missing Long Description}}
     895 * Display adjacent post link.
     896 *
     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) {
     
    968934
    969935/**
    970  * {@internal Missing Short Description}}
    971  *
    972  * {@internal Missing Long Description}}
     936 * Retrieve get links for page numbers.
    973937 *
    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) {
     
    1032996
    1033997/**
    1034  * {@internal Missing Short Description}}
    1035  *
    1036  * {@internal Missing Long Description}}
     998 * Retrieve next posts pages link.
     999 *
    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) {
     
    10551018
    10561019/**
    1057  * {@internal Missing Short Description}}
    1058  *
    1059  * {@internal Missing Long Description}}
     1020 * Display the next posts pages link.
    10601021 *
    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) {
     
    10681029
    10691030/**
    1070  * {@internal Missing Short Description}}
    1071  *
    1072  * {@internal Missing Long Description}}
     1031 * Display the next posts pages link.
    10731032 *
    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) {
     
    10941053
    10951054/**
    1096  * {@internal Missing Short Description}}
    1097  *
    1098  * {@internal Missing Long Description}}
    1099  *
    1100  * @since 2.0.10 Backported
    1101  * @since 2.1.3
    1102  *
    1103  * @return unknown
     1055 * Retrieve previous post pages link.
     1056 *
     1057 * Will only return string, if not on a single page or post.
     1058 *
     1059 * Backported to 2.0.10 from 2.1.3.
     1060 *
     1061 * @since 2.0.10
     1062 *
     1063 * @return string|null
    11041064 */
    11051065function get_previous_posts_page_link() {
     
    11151075
    11161076/**
    1117  * {@internal Missing Short Description}}
    1118  *
    1119  * {@internal Missing Long Description}}
     1077 * Display previous posts pages link.
    11201078 *
    11211079 * @since 0.71
    1122  *
    11231080 */
    11241081function previous_posts() {
     
    11271084
    11281085/**
    1129  * {@internal Missing Short Description}}
    1130  *
    1131  * {@internal Missing Long Description}}
     1086 * Display previous posts page link.
    11321087 *
    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') {
     
    11461101
    11471102/**
    1148  * {@internal Missing Short Description}}
    1149  *
    1150  * {@internal Missing Long Description}}
     1103 * Display post pages link navigation for previous and next pages.
    11511104 *
    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 »') {
     
    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;
     
    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;
     
    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;
     
    12551231}
    12561232
    1257 /** Create pagination links for the comments on the current post
    1258  *
    1259  * @package WordPress
    1260  * @see paginate_links
    1261  * @since 2.7
     1233/**
     1234 * Create pagination links for the comments on the current post.
     1235 *
     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()) {
     
    12921268
    12931269/**
    1294  * {@internal Missing Short Description}}
    1295  *
    1296  * {@internal Missing Long Description}}
    1297  *
    1298  * @since unknown
    1299  *
    1300  * @return unknown
     1270 * Retrieve shortcut link.
     1271 *
     1272 * Use this in 'a' element 'href' attribute.
     1273 *
     1274 * @since 2.6.0
     1275 *
     1276 * @return string
    13011277 */
    13021278function get_shortcut_link() {
     
    13361312 * overridden.
    13371313 *
     1314 * @package WordPress
    13381315 * @since 2.6.0
    13391316 *
Note: See TracChangeset for help on using the changeset viewer.