Index: link-template.php
===================================================================
--- link-template.php	(revision 8786)
+++ link-template.php	(working copy)
@@ -1,15 +1,34 @@
 <?php
+/**
+ * WordPress Link Template Functions
+ *
+ * @package WordPress
+ * @subpackage Template
+ */
 
-
+/**
+ * the_permalink() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.2.0
+ * @uses apply_filters() 
+ */
 function the_permalink() {
 	echo apply_filters('the_permalink', get_permalink());
 }
 
 
 /**
+ * user_trailingshashit() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
  * Conditionally adds a trailing slash if the permalink structure
  * has a trailing slash, strips the trailing slash if not
- * @global object Uses $wp_rewrite
+ * @uses $wp_rewrite
  * @param $string string a URL with or without a trailing slash
  * @param $type_of_url string the type of URL being considered (e.g. single, category, etc) for use in the filter
  * @return string
@@ -27,7 +46,15 @@
 	return $string;
 }
 
-
+/**
+ * permalink_anchor() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 0.71
+ *
+ * @param unknown_type $mode
+ */
 function permalink_anchor($mode = 'id') {
 	global $post;
 	switch ( strtolower($mode) ) {
@@ -42,7 +69,16 @@
 	}
 }
 
-
+/**
+ * get_permalink() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.0.0
+ *
+ * @param unknown_type $id
+ * @return unknown
+ */
 function get_permalink($id = 0, $leavename=false) {
 	$rewritecode = array(
 		'%year%',
@@ -119,12 +155,32 @@
 	}
 }
 
-// get permalink from post ID
+/**
+ * post_permalink() - Retrieve permalink from post ID
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.0.0
+ *
+ * @param unknown_type $post_id
+ * @param unknown_type $deprecated
+ * @return unknown
+ */
 function post_permalink($post_id = 0, $deprecated = '') {
 	return get_permalink($post_id);
 }
 
 // Respects page_on_front.  Use this one.
+/**
+ * get_page_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.5.0
+ *
+ * @param unknown_type $id
+ * @return unknown
+ */
 function get_page_link($id = false, $leavename = false) {
 	global $post;
 
@@ -140,7 +196,19 @@
 	return apply_filters('page_link', $link, $id);
 }
 
-// Ignores page_on_front.  Internal use only.
+/**
+ * _get_page_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * Ignores page_on_front. Internal use only.
+ *
+ * @since 2.1.0
+ * @access private
+ *
+ * @param unknown_type $id
+ * @return unknown
+ */
 function _get_page_link( $id = false, $leavename = false ) {
 	global $post, $wp_rewrite;
 
@@ -163,6 +231,16 @@
 	return apply_filters( '_get_page_link', $link, $id );
 }
 
+/**
+ * get_attachment_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.0.0
+ *
+ * @param unknown_type $id
+ * @return unknown
+ */
 function get_attachment_link($id = false) {
 	global $post, $wp_rewrite;
 
@@ -194,6 +272,16 @@
 	return apply_filters('attachment_link', $link, $id);
 }
 
+/**
+ * get_year_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.5.0
+ *
+ * @param unknown_type $year
+ * @return unknown
+ */
 function get_year_link($year) {
 	global $wp_rewrite;
 	if ( !$year )
@@ -207,6 +295,17 @@
 	}
 }
 
+/**
+ * get_month_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.0.0
+ *
+ * @param unknown_type $year
+ * @param unknown_type $month
+ * @return unknown
+ */
 function get_month_link($year, $month) {
 	global $wp_rewrite;
 	if ( !$year )
@@ -223,6 +322,18 @@
 	}
 }
 
+/**
+ * get_day_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.0.0
+ *
+ * @param unknown_type $year
+ * @param unknown_type $month
+ * @param unknown_type $day
+ * @return unknown
+ */
 function get_day_link($year, $month, $day) {
 	global $wp_rewrite;
 	if ( !$year )
@@ -243,6 +354,16 @@
 	}
 }
 
+/**
+ * get_feed_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.5.0
+ *
+ * @param unknown_type $feed
+ * @return unknown
+ */
 function get_feed_link($feed = '') {
 	global $wp_rewrite;
 
@@ -272,6 +393,17 @@
 	return apply_filters('feed_link', $output, $feed);
 }
 
+/**
+ * get_post_comments_feed_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $post_id
+ * @param unknown_type $feed
+ * @return unknown
+ */
 function get_post_comments_feed_link($post_id = '', $feed = '') {
 	global $id;
 
@@ -297,18 +429,20 @@
 	return apply_filters('post_comments_feed_link', $url);
 }
 
-/** post_comments_feed_link() - Output the comment feed link for a post.
+/**
+ * post_comments_feed_link() - Output the comment feed link for a post.
  *
- * Prints out the comment feed link for a post.  Link text is placed in the
- * anchor.  If no link text is specified, default text is used.  If no post ID
- * is specified, the current post is used.
+ * Prints out the comment feed link for a post. Link text is placed in the
+ * anchor. If no link text is specified, default text is used.  If no post
+ * ID is specified, the current post is used.
  *
  * @package WordPress
  * @subpackage Feed
  * @since 2.5
  *
- * @param string Descriptive text
- * @param int Optional post ID.  Default to current post.
+ * @param string $link_text Descriptive text
+ * @param int $post_id Optional post ID.  Default to current post.
+ * @param string $feed Optional. {@internal Missing Description}}
  * @return string Link to the comment feed for the current post
 */
 function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) {
@@ -356,10 +490,11 @@
 	return $link;
 }
 
-/** Get the feed link for a given category
+/**
+ * get_category_feed_link() - Get the feed link for a category
  *
- * Returns a link to the feed for all posts in a given category.  A specific feed can be requested
- * or left blank to get the default feed.
+ * Returns a link to the feed for all post in a given category. A specific
+ * feed can be requested or left blank to get the default feed.
  *
  * @package WordPress
  * @subpackage Feed
@@ -399,6 +534,17 @@
 	return $link;
 }
 
+/**
+ * get_tag_feed_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.3.0
+ *
+ * @param unknown_type $tag_id
+ * @param unknown_type $feed
+ * @return unknown
+ */
 function get_tag_feed_link($tag_id, $feed = '') {
 	$tag_id = (int) $tag_id;
 
@@ -428,6 +574,17 @@
 	return $link;
 }
 
+/**
+ * get_search_feed_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.5.0
+ *
+ * @param unknown_type $search_query
+ * @param unknown_type $feed
+ * @return unknown
+ */
 function get_search_feed_link($search_query = '', $feed = '') {
 	if ( empty($search_query) )
 		$search = attribute_escape(get_search_query());
@@ -444,6 +601,17 @@
 	return $link;
 }
 
+/**
+ * get_search_comment_feed_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.5.0
+ *
+ * @param unknown_type $search_query
+ * @param unknown_type $feed
+ * @return unknown
+ */
 function get_search_comments_feed_link($search_query = '', $feed = '') {
 	if ( empty($search_query) )
 		$search = attribute_escape(get_search_query());
@@ -460,6 +628,16 @@
 	return $link;
 }
 
+/**
+ * get_edit_post_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.3.0
+ *
+ * @param unknown_type $id
+ * @return unknown
+ */
 function get_edit_post_link( $id = 0, $context = 'display' ) {
 	if ( !$post = &get_post( $id ) )
 		return;
@@ -500,6 +678,17 @@
 	return apply_filters( 'get_edit_post_link', admin_url("$file.php?{$action}$var=$post->ID"), $post->ID, $context );
 }
 
+/**
+ * edit_post_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.0.0
+ *
+ * @param unknown_type $link
+ * @param unknown_type $before
+ * @param unknown_type $after
+ */
 function edit_post_link( $link = 'Edit This', $before = '', $after = '' ) {
 	global $post;
 
@@ -515,6 +704,16 @@
 	echo $before . apply_filters( 'edit_post_link', $link, $post->ID ) . $after;
 }
 
+/**
+ * get_edit_comment_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.3.0
+ *
+ * @param unknown_type $comment_id
+ * @return unknown
+ */
 function get_edit_comment_link( $comment_id = 0 ) {
 	$comment = &get_comment( $comment_id );
 	$post = &get_post( $comment->comment_post_ID );
@@ -531,6 +730,17 @@
 	return apply_filters( 'get_edit_comment_link', $location );
 }
 
+/**
+ * edit_comment_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.0.0
+ *
+ * @param unknown_type $link
+ * @param unknown_type $before
+ * @param unknown_type $after
+ */
 function edit_comment_link( $link = 'Edit This', $before = '', $after = '' ) {
 	global $comment, $post;
 
@@ -572,14 +782,48 @@
 
 // Navigation links
 
+/**
+ * get_previous_post() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.5.0
+ *
+ * @param unknown_type $in_same_cat
+ * @param unknown_type $excluded_categories
+ * @return unknown
+ */
 function get_previous_post($in_same_cat = false, $excluded_categories = '') {
 	return get_adjacent_post($in_same_cat, $excluded_categories);
 }
 
+/**
+ * get_next_post() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.5.0
+ *
+ * @param unknown_type $in_same_cat
+ * @param unknown_type $excluded_categories
+ * @return unknown
+ */
 function get_next_post($in_same_cat = false, $excluded_categories = '') {
 	return get_adjacent_post($in_same_cat, $excluded_categories, false);
 }
 
+/**
+ * get_adjacent_post() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.5.0
+ *
+ * @param unknown_type $in_same_cat
+ * @param unknown_type $excluded_categories
+ * @param unknown_type $previous
+ * @return unknown
+ */
 function get_adjacent_post($in_same_cat = false, $excluded_categories = '', $previous = true) {
 	global $post, $wpdb;
 
@@ -623,14 +867,51 @@
 	return $wpdb->get_row("SELECT p.* FROM $wpdb->posts AS p $join $where $sort");
 }
 
+/**
+ * previous_post_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.5.0
+ *
+ * @param unknown_type $format
+ * @param unknown_type $link
+ * @param unknown_type $in_same_cat
+ * @param unknown_type $excluded_categories
+ */
 function previous_post_link($format='&laquo; %link', $link='%title', $in_same_cat = false, $excluded_categories = '') {
 	adjacent_post_link($format, $link, $in_same_cat, $excluded_categories, true);
 }
 
+/**
+ * next_post_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.5.0
+ *
+ * @param unknown_type $format
+ * @param unknown_type $link
+ * @param unknown_type $in_same_cat
+ * @param unknown_type $excluded_categories
+ */
 function next_post_link($format='%link &raquo;', $link='%title', $in_same_cat = false, $excluded_categories = '') {
 	adjacent_post_link($format, $link, $in_same_cat, $excluded_categories, false);
 }
 
+/**
+ * adjacent_post_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.5.0
+ *
+ * @param unknown_type $format
+ * @param unknown_type $link
+ * @param unknown_type $in_same_cat
+ * @param unknown_type $excluded_categories
+ * @param unknown_type $previous
+ */
 function adjacent_post_link($format, $link, $in_same_cat = false, $excluded_categories = '', $previous = true) {
 	if ( $previous && is_attachment() )
 		$post = & get_post($GLOBALS['post']->post_parent);
@@ -656,6 +937,16 @@
 	echo apply_filters( "{$adjacent}_post_link", $format, $link );
 }
 
+/**
+ * get_pagenum_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.5.0
+ *
+ * @param unknown_type $pagenum
+ * @return unknown
+ */
 function get_pagenum_link($pagenum = 1) {
 	global $wp_rewrite;
 
@@ -710,6 +1001,17 @@
 	return $result;
 }
 
+/**
+ * get_next_posts_page_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.0.10 Backported
+ * @since 2.1.3
+ *
+ * @param unknown_type $max_page
+ * @return unknown
+ */
 function get_next_posts_page_link($max_page = 0) {
 	global $paged;
 
@@ -722,10 +1024,29 @@
 	}
 }
 
+/**
+ * next_posts() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 0.71
+ *
+ * @param unknown_type $max_page
+ */
 function next_posts($max_page = 0) {
 	echo clean_url(get_next_posts_page_link($max_page));
 }
 
+/**
+ * next_posts_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 0.71
+ *
+ * @param unknown_type $label
+ * @param unknown_type $max_page
+ */
 function next_posts_link($label='Next Page &raquo;', $max_page=0) {
 	global $paged, $wp_query;
 	if ( !$max_page ) {
@@ -742,6 +1063,16 @@
 	}
 }
 
+/**
+ * get_previous_posts_page_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.0.10 Backported
+ * @since 2.1.3
+ *
+ * @return unknown
+ */
 function get_previous_posts_page_link() {
 	global $paged;
 
@@ -753,10 +1084,27 @@
 	}
 }
 
+/**
+ * previous_posts() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 0.71
+ *
+ */
 function previous_posts() {
 	echo clean_url(get_previous_posts_page_link());
 }
 
+/**
+ * previous_posts_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 0.71
+ *
+ * @param unknown_type $label
+ */
 function previous_posts_link($label='&laquo; Previous Page') {
 	global $paged;
 	if ( (!is_single())	&& ($paged > 1) ) {
@@ -767,6 +1115,17 @@
 	}
 }
 
+/**
+ * posts_nav_link() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 0.71
+ *
+ * @param unknown_type $sep
+ * @param unknown_type $prelabel
+ * @param unknown_type $nxtlabel
+ */
 function posts_nav_link($sep=' &#8212; ', $prelabel='&laquo; Previous Page', $nxtlabel='Next Page &raquo;') {
 	global $wp_query;
 	if ( !is_singular() ) {