Make WordPress Core

Ticket #5642: 5642.r8947.diff

File 5642.r8947.diff, 19.6 KB (added by jacobsantos, 15 years ago)

Inline documentation skeleton for link-template.php based off of r8947

  • link-template.php

     
    11<?php
     2/**
     3 * WordPress Link Template Functions
     4 *
     5 * @package WordPress
     6 * @subpackage Template
     7 */
    28
    3 
     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 
    921/**
     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
    1533 * @return string
     
    2745        return $string;
    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;
    3359        switch ( strtolower($mode) ) {
     
    4268        }
    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(
    4883                '%year%',
     
    119154        }
    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);
    125170}
    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;
    130185
     
    140195        return apply_filters('page_link', $link, $id);
    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;
    146213
     
    163230        return apply_filters( '_get_page_link', $link, $id );
    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;
    168245
     
    194271        return apply_filters('attachment_link', $link, $id);
    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;
    199286        if ( !$year )
     
    207294        }
    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;
    212310        if ( !$year )
     
    223321        }
    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;
    228338        if ( !$year )
     
    243353        }
    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;
    248368
     
    272392        return apply_filters('feed_link', $output, $feed);
    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;
    277408
     
    297428        return apply_filters('post_comments_feed_link', $url);
    298429}
    299430
    300 /** post_comments_feed_link() - Output the comment feed link for a post.
     431/**
     432 * Display the comment feed link for a post.
    301433 *
    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.
     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
     440 * @since 2.5.0
    309441 *
    310  * @param string Descriptive text
    311  * @param int Optional post ID.  Default to current post.
     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*/
    314447function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) {
     
    319452        echo "<a href='$url'>$link_text</a>";
    320453}
    321454
    322 /** Get the feed link for a given author
     455/**
     456 * Retrieve the feed link for a given author.
    323457 *
    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.
     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
     463 * @since 2.5.0
    330464 *
    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
     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 = '' ) {
    336470        $author_id = (int) $author_id;
     
    356490        return $link;
    357491}
    358492
    359 /** Get the feed link for a given category
     493/**
     494 * Retrieve the feed link for a category.
    360495 *
    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.
     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
     501 * @since 2.5.0
    367502 *
    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
     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 = '') {
    373508        $cat_id = (int) $cat_id;
     
    399534        return $link;
    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;
    404550
     
    428574        return $link;
    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) )
    433590                $search = attribute_escape(get_search_query());
     
    444601        return $link;
    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) )
    449617                $search = attribute_escape(get_search_query());
     
    460628        return $link;
    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 ) )
    465643                return;
     
    500678        return apply_filters( 'get_edit_post_link', admin_url("$file.php?{$action}$var=$post->ID"), $post->ID, $context );
    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;
    505694
     
    515704        echo $before . apply_filters( 'edit_post_link', $link, $post->ID ) . $after;
    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 );
    520719        $post = &get_post( $comment->comment_post_ID );
     
    531730        return apply_filters( 'get_edit_comment_link', $location );
    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;
    536746
     
    551761                return $link;
    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 );
    556776
     
    561781        return apply_filters( 'get_edit_bookmark_link', $location, $link->link_id );
    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);
    566798
     
    576808
    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;
    589855
     
    627893        return $wpdb->get_row("SELECT p.* FROM $wpdb->posts AS p $join $where $sort");
    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() )
    640943                $post = & get_post($GLOBALS['post']->post_parent);
     
    663966        echo apply_filters( "{$adjacent}_post_link", $format, $link );
    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;
    668981
     
    7171030        return $result;
    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;
    7221046
     
    7291053        }
    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;
    7381081        if ( !$max_page ) {
     
    7491092        }
    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;
    7541107
     
    7601113        }
    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;
    7691139        if ( (!is_single())     && ($paged > 1) ) {
     
    7741144        }
    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;
    7791160        if ( !is_singular() ) {
     
    7931174        }
    7941175}
    7951176
     1177/**
     1178 * {@internal Missing Short Description}}
     1179 *
     1180 * {@internal Missing Long Description}}
     1181 *
     1182 * @since unknown
     1183 *
     1184 * @return unknown
     1185 */
    7961186function get_shortcut_link() {
    7971187        $link = "javascript:
    7981188                        var d=document,
     
    8221212        return apply_filters('shortcut_link', $link);
    8231213}
    8241214
    825 /** Return the site url
     1215/**
     1216 * Retrieve the site url.
    8261217 *
     1218 * Returns the 'site_url' option with the appropriate protocol,  'https' if
     1219 * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
     1220 * overridden.
    8271221 *
    828  * @package WordPress
    829  * @since 2.6
     1222 * @since 2.6.0
    8301223 *
    831  * Returns the 'site_url' option with the appropriate protocol,  'https' if is_ssl() and 'http' otherwise.
    832  * If $scheme is 'http' or 'https', is_ssl() is overridden.
    833  *
    834  * @param string $path Optional path relative to the site url
    835  * @param string $scheme Optional scheme to give the site url context. Currently 'http','https', 'login', 'login_post', or 'admin'
    836  * @return string Site url link with optional path appended
     1224 * @param string $path Optional. Path relative to the site url.
     1225 * @param string $scheme Optional. Scheme to give the site url context. Currently 'http','https', 'login', 'login_post', or 'admin'.
     1226 * @return string Site url link with optional path appended.
    8371227*/
    8381228function site_url($path = '', $scheme = null) {
    8391229        // should the list of allowed schemes be maintained elsewhere?
     
    8571247        return apply_filters('site_url', $url, $path, $orig_scheme);
    8581248}
    8591249
    860 /** Return the admin url
     1250/**
     1251 * Retrieve the url to the admin area.
    8611252 *
    862  *
    8631253 * @package WordPress
    864  * @since 2.6
     1254 * @since 2.6.0
    8651255 *
    866  * Returns the url to the admin area
    867  *
    8681256 * @param string $path Optional path relative to the admin url
    8691257 * @return string Admin url link with optional path appended
    8701258*/
     
    8771265        return $url;
    8781266}
    8791267
    880 /** Return the includes url
     1268/**
     1269 * Retrieve the url to the includes directory.
    8811270 *
    882  *
    8831271 * @package WordPress
    884  * @since 2.6
     1272 * @since 2.6.0
    8851273 *
    886  * Returns the url to the includes directory
    887  *
    888  * @param string $path Optional path relative to the includes url
    889  * @return string Includes url link with optional path appended
     1274 * @param string $path Optional. Path relative to the includes url.
     1275 * @return string Includes url link with optional path appended.
    8901276*/
    8911277function includes_url($path = '') {
    8921278        $url = site_url() . '/' . WPINC . '/';
     
    8971283        return $url;
    8981284}
    8991285
    900 /** Return the content url
     1286/**
     1287 * Retrieve the url to the content directory.
    9011288 *
    902  *
    9031289 * @package WordPress
    904  * @since 2.6
     1290 * @since 2.6.0
    9051291 *
    906  * Returns the url to the content directory
    907  *
    908  * @param string $path Optional path relative to the content url
    909  * @return string Content url link with optional path appended
     1292 * @param string $path Optional. Path relative to the content url.
     1293 * @return string Content url link with optional path appended.
    9101294*/
    9111295function content_url($path = '') {
    9121296        $scheme = ( is_ssl() ? 'https' : 'http' );
     
    9221306        return $url;
    9231307}
    9241308
    925 /** Return the plugins url
     1309/**
     1310 * Retrieve the url to the plugins directory.
    9261311 *
    927  *
    9281312 * @package WordPress
    929  * @since 2.6
     1313 * @since 2.6.0
    9301314 *
    931  * Returns the url to the plugins directory
    932  *
    933  * @param string $path Optional path relative to the plugins url
    934  * @return string Plugins url link with optional path appended
     1315 * @param string $path Optional. Path relative to the plugins url.
     1316 * @return string Plugins url link with optional path appended.
    9351317*/
    9361318function plugins_url($path = '') {
    9371319        $scheme = ( is_ssl() ? 'https' : 'http' );