Changeset 9136

Show
Ignore:
Timestamp:
10/13/08 22:00:07 (2 months ago)
Author:
ryan
Message:

doc skeleton for link-template. Props jacobsantos. see #5642

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/wp-includes/link-template.php

    r9097 r9136  
    11<?php 
    2  
    3  
     2/** 
     3 * WordPress Link Template Functions 
     4 * 
     5 * @package WordPress 
     6 * @subpackage Template 
     7 */ 
     8 
     9/** 
     10 * {@internal Missing Short Description}} 
     11 * 
     12 * {@internal Missing Long Description}} 
     13 * 
     14 * @since 1.2.0 
     15 * @uses apply_filters()  
     16 */ 
    417function the_permalink() { 
    518    echo apply_filters('the_permalink', get_permalink()); 
    619} 
    720 
    8  
    9 /** 
     21/** 
     22 * {@internal Missing Short Description}} 
     23 * 
    1024 * Conditionally adds a trailing slash if the permalink structure 
    1125 * has a trailing slash, strips the trailing slash if not 
    12  * @global object Uses $wp_rewrite 
     26 * {@internal Missing Long Description}} 
     27 * 
     28 * @since 2.2.0 
     29 * @uses $wp_rewrite 
     30 * 
    1331 * @param $string string a URL with or without a trailing slash 
    1432 * @param $type_of_url string the type of URL being considered (e.g. single, category, etc) for use in the filter 
    …… 
    2846} 
    2947 
    30  
     48/** 
     49 * {@internal Missing Short Description}} 
     50 * 
     51 * {@internal Missing Long Description}} 
     52 * 
     53 * @since 0.71 
     54 * 
     55 * @param unknown_type $mode 
     56 */ 
    3157function permalink_anchor($mode = 'id') { 
    3258    global $post; 
    …… 
    4369} 
    4470 
    45  
     71/** 
     72 * {@internal Missing Short Description}} 
     73 * 
     74 * {@internal Missing Long Description}} 
     75 * 
     76 * @since 1.0.0 
     77 * 
     78 * @param unknown_type $id 
     79 * @return unknown 
     80 */ 
    4681function get_permalink($id = 0, $leavename=false) { 
    4782    $rewritecode = array( 
    …… 
    120155} 
    121156 
    122 // get permalink from post ID 
     157/** 
     158 * Retrieve permalink from post ID. 
     159 * 
     160 * {@internal Missing Long Description}} 
     161 * 
     162 * @since 1.0.0 
     163 * 
     164 * @param unknown_type $post_id 
     165 * @param unknown_type $deprecated 
     166 * @return unknown 
     167 */ 
    123168function post_permalink($post_id = 0, $deprecated = '') { 
    124169    return get_permalink($post_id); 
    …… 
    126171 
    127172// Respects page_on_front.  Use this one. 
     173/** 
     174 * {@internal Missing Short Description}} 
     175 * 
     176 * {@internal Missing Long Description}} 
     177 * 
     178 * @since 1.5.0 
     179 * 
     180 * @param unknown_type $id 
     181 * @return unknown 
     182 */ 
    128183function get_page_link($id = false, $leavename = false) { 
    129184    global $post; 
    …… 
    141196} 
    142197 
    143 // Ignores page_on_front.  Internal use only. 
     198/** 
     199 * {@internal Missing Short Description}} 
     200 * 
     201 * {@internal Missing Long Description}} 
     202 * 
     203 * Ignores page_on_front. Internal use only. 
     204 * 
     205 * @since 2.1.0 
     206 * @access private 
     207 * 
     208 * @param unknown_type $id 
     209 * @return unknown 
     210 */ 
    144211function _get_page_link( $id = false, $leavename = false ) { 
    145212    global $post, $wp_rewrite; 
    …… 
    164231} 
    165232 
     233/** 
     234 * {@internal Missing Short Description}} 
     235 * 
     236 * {@internal Missing Long Description}} 
     237 * 
     238 * @since 2.0.0 
     239 * 
     240 * @param unknown_type $id 
     241 * @return unknown 
     242 */ 
    166243function get_attachment_link($id = false) { 
    167244    global $post, $wp_rewrite; 
    …… 
    195272} 
    196273 
     274/** 
     275 * {@internal Missing Short Description}} 
     276 * 
     277 * {@internal Missing Long Description}} 
     278 * 
     279 * @since 1.5.0 
     280 * 
     281 * @param unknown_type $year 
     282 * @return unknown 
     283 */ 
    197284function get_year_link($year) { 
    198285    global $wp_rewrite; 
    …… 
    208295} 
    209296 
     297/** 
     298 * {@internal Missing Short Description}} 
     299 * 
     300 * {@internal Missing Long Description}} 
     301 * 
     302 * @since 1.0.0 
     303 * 
     304 * @param unknown_type $year 
     305 * @param unknown_type $month 
     306 * @return unknown 
     307 */ 
    210308function get_month_link($year, $month) { 
    211309    global $wp_rewrite; 
    …… 
    224322} 
    225323 
     324/** 
     325 * {@internal Missing Short Description}} 
     326 * 
     327 * {@internal Missing Long Description}} 
     328 * 
     329 * @since 1.0.0 
     330 * 
     331 * @param unknown_type $year 
     332 * @param unknown_type $month 
     333 * @param unknown_type $day 
     334 * @return unknown 
     335 */ 
    226336function get_day_link($year, $month, $day) { 
    227337    global $wp_rewrite; 
    …… 
    244354} 
    245355 
     356/** 
     357 * {@internal Missing Short Description}} 
     358 * 
     359 * {@internal Missing Long Description}} 
     360 * 
     361 * @since 1.5.0 
     362 * 
     363 * @param unknown_type $feed 
     364 * @return unknown 
     365 */ 
    246366function get_feed_link($feed = '') { 
    247367    global $wp_rewrite; 
    …… 
    273393} 
    274394 
     395/** 
     396 * {@internal Missing Short Description}} 
     397 * 
     398 * {@internal Missing Long Description}} 
     399 * 
     400 * @since 2.2.0 
     401 * 
     402 * @param unknown_type $post_id 
     403 * @param unknown_type $feed 
     404 * @return unknown 
     405 */ 
    275406function get_post_comments_feed_link($post_id = '', $feed = '') { 
    276407    global $id; 
    …… 
    298429} 
    299430 
    300 /** post_comments_feed_link() - Output the comment feed link for a post. 
    301  * 
    302  * Prints out the comment feed link for a post.  Link text is placed in the 
    303  * anchor.  If no link text is specified, default text is used.  If no post ID 
    304  * is specified, the current post is used. 
     431/** 
     432 * Display the comment feed link for a post. 
     433 * 
     434 * Prints out the comment feed link for a post. Link text is placed in the 
     435 * anchor. If no link text is specified, default text is used. If no post ID is 
     436 * specified, the current post is used. 
    305437 * 
    306438 * @package WordPress 
    307439 * @subpackage Feed 
    308  * @since 2.5 
    309  * 
    310  * @param string Descriptive text 
    311  * @param int Optional post ID.  Default to current post. 
     440 * @since 2.5.0 
     441 * 
     442 * @param string $link_text Descriptive text 
     443 * @param int $post_id Optional post ID.  Default to current post. 
     444 * @param string $feed Optional. {@internal Missing Description}} 
    312445 * @return string Link to the comment feed for the current post 
    313446*/ 
    …… 
    320453} 
    321454 
    322 /** Get the feed link for a given author 
    323  * 
    324  * Returns a link to the feed for all posts by a given author.  A specific feed can be requested 
    325  * or left blank to get the default feed. 
     455/** 
     456 * Retrieve the feed link for a given author. 
     457 * 
     458 * Returns a link to the feed for all posts by a given author. A specific feed 
     459 * can be requested or left blank to get the default feed. 
    326460 * 
    327461 * @package WordPress 
    328462 * @subpackage Feed 
    329  * @since 2.5 
    330  * 
    331  * @param int $author_id ID of an author 
    332  * @param string $feed Feed type 
    333  * @return string Link to the feed for the author specified by $author_id 
     463 * @since 2.5.0 
     464 * 
     465 * @param int $author_id ID of an author. 
     466 * @param string $feed Feed type. 
     467 * @return string Link to the feed for the author specified by $author_id. 
    334468*/ 
    335469function get_author_feed_link( $author_id, $feed = '' ) { 
    …… 
    357491} 
    358492 
    359 /** Get the feed link for a given category 
    360  * 
    361  * Returns a link to the feed for all posts in a given category.  A specific feed can be requested 
    362  * or left blank to get the default feed. 
     493/** 
     494 * Retrieve the feed link for a category. 
     495 * 
     496 * Returns a link to the feed for all post in a given category. A specific feed 
     497 * can be requested or left blank to get the default feed. 
    363498 * 
    364499 * @package WordPress 
    365500 * @subpackage Feed 
    366  * @since 2.5 
    367  * 
    368  * @param int $cat_id ID of a category 
    369  * @param string $feed Feed type 
    370  * @return string Link to the feed for the category specified by $cat_id 
     501 * @since 2.5.0 
     502 * 
     503 * @param int $cat_id ID of a category. 
     504 * @param string $feed Feed type. 
     505 * @return string Link to the feed for the category specified by $cat_id. 
    371506*/ 
    372507function get_category_feed_link($cat_id, $feed = '') { 
    …… 
    400535} 
    401536 
     537/** 
     538 * {@internal Missing Short Description}} 
     539 * 
     540 * {@internal Missing Long Description}} 
     541 * 
     542 * @since 2.3.0 
     543 * 
     544 * @param unknown_type $tag_id 
     545 * @param unknown_type $feed 
     546 * @return unknown 
     547 */ 
    402548function get_tag_feed_link($tag_id, $feed = '') { 
    403549    $tag_id = (int) $tag_id; 
    …… 
    429575} 
    430576 
     577/** 
     578 * {@internal Missing Short Description}} 
     579 * 
     580 * {@internal Missing Long Description}} 
     581 * 
     582 * @since 2.5.0 
     583 * 
     584 * @param unknown_type $search_query 
     585 * @param unknown_type $feed 
     586 * @return unknown 
     587 */ 
    431588function get_search_feed_link($search_query = '', $feed = '') { 
    432589    if ( empty($search_query) ) 
    …… 
    445602} 
    446603 
     604/** 
     605 * {@internal Missing Short Description}} 
     606 * 
     607 * {@internal Missing Long Description}} 
     608 * 
     609 * @since 2.5.0 
     610 * 
     611 * @param unknown_type $search_query 
     612 * @param unknown_type $feed 
     613 * @return unknown 
     614 */ 
    447615function get_search_comments_feed_link($search_query = '', $feed = '') { 
    448616    if ( empty($search_query) ) 
    …… 
    461629} 
    462630 
     631/** 
     632 * {@internal Missing Short Description}} 
     633 * 
     634 * {@internal Missing Long Description}} 
     635 * 
     636 * @since 2.3.0 
     637 * 
     638 * @param unknown_type $id 
     639 * @return unknown 
     640 */ 
    463641function get_edit_post_link( $id = 0, $context = 'display' ) { 
    464642    if ( !$post = &get_post( $id ) ) 
    …… 
    501679} 
    502680 
     681/** 
     682 * {@internal Missing Short Description}} 
     683 * 
     684 * {@internal Missing Long Description}} 
     685 * 
     686 * @since 1.0.0 
     687 * 
     688 * @param unknown_type $link 
     689 * @param unknown_type $before 
     690 * @param unknown_type $after 
     691 */ 
    503692function edit_post_link( $link = 'Edit This', $before = '', $after = '' ) { 
    504693    global $post; 
    …… 
    516705} 
    517706 
     707/** 
     708 * {@internal Missing Short Description}} 
     709 * 
     710 * {@internal Missing Long Description}} 
     711 * 
     712 * @since 2.3.0 
     713 * 
     714 * @param unknown_type $comment_id 
     715 * @return unknown 
     716 */ 
    518717function get_edit_comment_link( $comment_id = 0 ) { 
    519718    $comment = &get_comment( $comment_id ); 
    …… 
    532731} 
    533732 
     733/** 
     734 * {@internal Missing Short Description}} 
     735 * 
     736 * {@internal Missing Long Description}} 
     737 * 
     738 * @since 1.0.0 
     739 * 
     740 * @param unknown_type $link 
     741 * @param unknown_type $before 
     742 * @param unknown_type $after 
     743 */ 
    534744function edit_comment_link( $link = 'Edit This', $before = '', $after = '', $echo = true ) { 
    535745    global $comment, $post; 
    …… 
    552762} 
    553763 
     764/** 
     765 * {@internal Missing Short Description}} 
     766 * 
     767 * {@internal Missing Long Description}} 
     768 * 
     769 * @since unknown 
     770 * 
     771 * @param unknown_type $link 
     772 * @return unknown 
     773 */ 
    554774function get_edit_bookmark_link( $link = 0 ) { 
    555775    $link = &get_bookmark( $link ); 
    …… 
    562782} 
    563783 
     784/** 
     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 
     795 */ 
    564796function edit_bookmark_link( $link = '', $before = '', $after = '', $bookmark = null ) { 
    565797    $bookmark = get_bookmark($bookmark); 
    …… 
    577809// Navigation links 
    578810 
     811/** 
     812 * {@internal Missing Short Description}} 
     813 * 
     814 * {@internal Missing Long Description}} 
     815 * 
     816 * @since 1.5.0 
     817 * 
     818 * @param unknown_type $in_same_cat 
     819 * @param unknown_type $excluded_categories 
     820 * @return unknown 
     821 */ 
    579822function get_previous_post($in_same_cat = false, $excluded_categories = '') { 
    580823    return get_adjacent_post($in_same_cat, $excluded_categories); 
    581824} 
    582825 
     826/** 
     827 * {@internal Missing Short Description}} 
     828 * 
     829 * {@internal Missing Long Description}} 
     830 * 
     831 * @since 1.5.0 
     832 * 
     833 * @param unknown_type $in_same_cat 
     834 * @param unknown_type $excluded_categories 
     835 * @return unknown 
     836 */ 
    583837function get_next_post($in_same_cat = false, $excluded_categories = '') { 
    584838    return get_adjacent_post($in_same_cat, $excluded_categories, false); 
    585839} 
    586840 
     841/** 
     842 * {@internal Missing Short Description}} 
     843 * 
     844 * {@internal Missing Long Description}} 
     845 * 
     846 * @since 2.5.0 
     847 * 
     848 * @param unknown_type $in_same_cat 
     849 * @param unknown_type $excluded_categories 
     850 * @param unknown_type $previous 
     851 * @return unknown 
     852 */ 
    587853function get_adjacent_post($in_same_cat = false, $excluded_categories = '', $previous = true) { 
    588854    global $post, $wpdb; 
    …… 
    628894} 
    629895 
     896/** 
     897 * {@internal Missing Short Description}} 
     898 * 
     899 * {@internal Missing Long Description}} 
     900 * 
     901 * @since 1.5.0 
     902 * 
     903 * @param unknown_type $format 
     904 * @param unknown_type $link 
     905 * @param unknown_type $in_same_cat 
     906 * @param unknown_type $excluded_categories 
     907 */ 
    630908function previous_post_link($format='&laquo; %link', $link='%title', $in_same_cat = false, $excluded_categories = '') { 
    631909    adjacent_post_link($format, $link, $in_same_cat, $excluded_categories, true); 
    632910} 
    633911 
     912/** 
     913 * {@internal Missing Short Description}} 
     914 * 
     915 * {@internal Missing Long Description}} 
     916 * 
     917 * @since 1.5.0 
     918 * 
     919 * @param unknown_type $format 
     920 * @param unknown_type $link 
     921 * @param unknown_type $in_same_cat 
     922 * @param unknown_type $excluded_categories 
     923 */ 
    634924function next_post_link($format='%link &raquo;', $link='%title', $in_same_cat = false, $excluded_categories = '') { 
    635925    adjacent_post_link($format, $link, $in_same_cat, $excluded_categories, false); 
    636926} 
    637927 
     928/** 
     929 * {@internal Missing Short Description}} 
     930 * 
     931 * {@internal Missing Long Description}} 
     932 * 
     933 * @since 2.5.0 
     934 * 
     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 
     940 */ 
    638941function adjacent_post_link($format, $link, $in_same_cat = false, $excluded_categories = '', $previous = true) { 
    639942    if ( $previous && is_attachment() ) 
    …… 
    664967} 
    665968 
     969/** 
     970 * {@internal Missing Short Description}} 
     971 * 
     972 * {@internal Missing Long Description}} 
     973 * 
     974 * @since 1.5.0 
     975 * 
     976 * @param unknown_type $pagenum 
     977 * @return unknown 
     978 */ 
    666979function get_pagenum_link($pagenum = 1) { 
    667980    global $wp_rewrite; 
    …… 
    7181031} 
    7191032 
     1033/** 
     1034 * {@internal Missing Short Description}} 
     1035 * 
     1036 * {@internal Missing Long Description}} 
     1037 * Backported from 2.1.3 to 2.0.10. 
     1038 * 
     1039 * @since 2.0.10 
     1040 * 
     1041 * @param unknown_type $max_page 
     1042 * @return unknown 
     1043 */ 
    7201044function get_next_posts_page_link($max_page = 0) { 
    7211045    global $paged; 
    …… 
    7301054} 
    7311055 
     1056/** 
     1057 * {@internal Missing Short Description}} 
     1058 * 
     1059 * {@internal Missing Long Description}} 
     1060 * 
     1061 * @since 0.71 
     1062 * 
     1063 * @param unknown_type $max_page 
     1064 */ 
    7321065function next_posts($max_page = 0) { 
    7331066    echo clean_url(get_next_posts_page_link($max_page)); 
    7341067} 
    7351068 
     1069/** 
     1070 * {@internal Missing Short Description}} 
     1071 * 
     1072 * {@internal Missing Long Description}} 
     1073 * 
     1074 * @since 0.71 
     1075 * 
     1076 * @param unknown_type $label 
     1077 * @param unknown_type $max_page 
     1078 */ 
    7361079function next_posts_link($label='Next Page &raquo;', $max_page=0) { 
    7371080    global $paged, $wp_query; 
    …… 
    7501093} 
    7511094 
     1095/** 
     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 
     1104 */ 
    7521105function get_previous_posts_page_link() { 
    7531106    global $paged; 
    …… 
    7611114} 
    7621115 
     1116/** 
     1117 * {@internal Missing Short Description}} 
     1118 * 
     1119 * {@internal Missing Long Description}} 
     1120 * 
     1121 * @since 0.71 
     1122 * 
     1123 */ 
    7631124function previous_posts() { 
    7641125    echo clean_url(get_previous_posts_page_link()); 
    7651126} 
    7661127 
     1128/** 
     1129 * {@internal Missing Short Description}} 
     1130 * 
     1131 * {@internal Missing Long Description}} 
     1132 * 
     1133 * @since 0.71 
     1134 * 
     1135 * @param unknown_type $label 
     1136 */ 
    7671137function previous_posts_link($label='&laquo; Previous Page') { 
    7681138    global $paged; 
    …… 
    7751145} 
    7761146 
     1147/** 
     1148 * {@internal Missing Short Description}} 
     1149 * 
     1150 * {@internal Missing Long Description}} 
     1151 * 
     1152 * @since 0.71 
     1153 * 
     1154 * @param unknown_type $sep 
     1155 * @param unknown_type $prelabel 
     1156 * @param unknown_type $nxtlabel 
     1157 */ 
    7771158function posts_nav_link($sep=' &#8212; ', $prelabel='&laquo; Previous Page', $nxtlabel='Next Page &raquo;') { 
    7781159    global $wp_query; 
    …… 
    9101291} 
    9111292 
     1293/** 
     1294 * {@internal Missing Short Description}} 
     1295 * 
     1296 * {@internal Missing Long Description}} 
     1297 * 
     1298 * @since unknown 
     1299 * 
     1300 * @return unknown 
     1301 */ 
    9121302function get_shortcut_link() { 
    9131303    $link = "javascript: 
    …… 
    9391329} 
    9401330 
    941 /** Return the site url 
    942  * 
    943  * 
    944  * @package WordPress 
    945  * @since 2.6 
    946  * 
    947  * Returns the 'site_url' option with the appropriate protocol,  'https' if is_ssl() and 'http' otherwise. 
    948  * If $scheme is 'http' or 'https', is_ssl() is overridden. 
    949  * 
    950  * @param string $path Optional path relative to the site url 
    951  * @param string $scheme Optional scheme to give the site url context. Currently 'http','https', 'login', 'login_post', or 'admin' 
    952  * @return string Site url link with optional path appended 
     1331/** 
     1332 * Retrieve the site url. 
     1333 * 
     1334 * Returns the 'site_url' option with the appropriate protocol,  'https' if 
     1335 * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is 
     1336 * overridden. 
     1337 * 
     1338 * @since 2.6.0 
     1339 * 
     1340 * @param string $path Optional. Path relative to the site url. 
     1341 * @param string $scheme Optional. Scheme to give the site url context. Currently 'http','https', 'login', 'login_post', or 'admin'. 
     1342 * @return string Site url link with optional path appended. 
    9531343*/ 
    9541344function site_url($path = '', $scheme = null) { 
    …… 
    9741364} 
    9751365 
    976 /** Return the admin url 
    977  * 
     1366/** 
     1367 * Retrieve the url to the admin area. 
    9781368 * 
    9791369 * @package WordPress 
    980  * @since 2.6 
    981  * 
    982  * Returns the url to the admin area 
     1370 * @since 2.6.0 
    9831371 * 
    9841372 * @param string $path Optional path relative to the admin url 
    …… 
    9941382} 
    9951383 
    996 /** Return the includes url 
    997  * 
     1384/** 
     1385 * Retrieve the url to the includes directory. 
    9981386 * 
    9991387 * @package WordPress 
    1000  * @since 2.6 
    1001  * 
    1002  * Returns the url to the includes directory 
    1003  * 
    1004  * @param string $path Optional path relative to the includes url 
    1005  * @return string Includes url link with optional path appended 
     1388 * @since 2.6.0 
     1389 * 
     1390 * @param string $path Optional. Path relative to the includes url. 
     1391 * @return string Includes url link with optional path appended. 
    10061392*/ 
    10071393function includes_url($path = '') { 
    …… 
    10141400} 
    10151401 
    1016 /** Return the content url 
    1017  * 
     1402/** 
     1403 * Retrieve the url to the content directory. 
    10181404 * 
    10191405 * @package WordPress 
    1020  * @since 2.6 
    1021  * 
    1022  * Returns the url to the content directory 
    1023  * 
    1024  * @param string $path Optional path relative to the content url 
    1025  * @return string Content url link with optional path appended 
     1406 * @since 2.6.0 
     1407 * 
     1408 * @param string $path Optional. Path relative to the content url. 
     1409 * @return string Content url link with optional path appended. 
    10261410*/ 
    10271411function content_url($path = '') { 
    …… 
    10391423} 
    10401424 
    1041 /** Return the plugins url 
    1042  * 
     1425/** 
     1426 * Retrieve the url to the plugins directory. 
    10431427 * 
    10441428 * @package WordPress 
    1045  * @since 2.6 
    1046  * 
    1047  * Returns the url to the plugins directory 
    1048  * 
    1049  * @param string $path Optional path relative to the plugins url 
    1050  * @return string Plugins url link with optional path appended 
     1429 * @since 2.6.0 
     1430 * 
     1431 * @param string $path Optional. Path relative to the plugins url. 
     1432 * @return string Plugins url link with optional path appended. 
    10511433*/ 
    10521434function plugins_url($path = '') {