Index: comment-functions.php
===================================================================
--- comment-functions.php	(revision 3698)
+++ comment-functions.php	(working copy)
@@ -2,6 +2,10 @@
 
 // Template functions
 
+/**
+ * Loads the comment template specified in $file
+ * @param string $file The file to load (default '/comments.php')
+ */
 function comments_template( $file = '/comments.php' ) {
 	global $wp_query, $withcomments, $post, $wpdb, $id, $comment, $user_login, $user_ID, $user_identity;
 
@@ -44,6 +48,10 @@
 	endif;
 }
 
+/**
+ * Parses and adds a new comment to the database
+ * @param array $commentdata Contains information on the comment
+ */
 function wp_new_comment( $commentdata ) {
 	$commentdata = apply_filters('preprocess_comment', $commentdata);
 
@@ -78,6 +86,11 @@
 	return $comment_ID;
 }
 
+/**
+ * Inserts a comment to the database
+ * @param array $commentdata Contains information on the comment
+ * @return int $id The new comment's id
+ */
 function wp_insert_comment($commentdata) {
 	global $wpdb;
 	extract($commentdata);
@@ -110,6 +123,11 @@
 	return $id;
 }
 
+/**
+ * Parses and returns comment information
+ * @param array $commentdata Contains information on the comment
+ * @return array $parseddata Parsed comment information
+ */
 function wp_filter_comment($commentdata) {
 	$commentdata['user_id']              = apply_filters('pre_user_id', $commentdata['user_ID']);
 	$commentdata['comment_agent']        = apply_filters('pre_comment_user_agent', $commentdata['comment_agent']);
@@ -122,6 +140,11 @@
 	return $commentdata;
 }
 
+/**
+ * Validates whether this comment is allowed to be made or not
+ * @param array $commentdata Contains information on the comment
+ * @return mixed $approved Signifies the approval status (0|1|'spam')
+ */
 function wp_allow_comment($commentdata) {
 	global $wpdb;
 	extract($commentdata);
@@ -171,7 +194,11 @@
 	return $approved;
 }
 
-
+/**
+ * Parses and updates an existing comment in the database
+ * @param array $commentdata Contains information on the comment
+ * @return int $success Success status (0|1)
+ */
 function wp_update_comment($commentarr) {
 	global $wpdb;
 
@@ -213,6 +240,11 @@
 	return $rval;
 }
 
+/**
+ * Removes a comment from the database
+ * @param int $comment_id Id of the comment to remove
+ * @return boolean $success Success status
+ */
 function wp_delete_comment($comment_id) {
 	global $wpdb;
 	do_action('delete_comment', $comment_id);
@@ -230,6 +262,11 @@
 	return true;
 }
 
+/**
+ * Removes nasty characters from a URL string
+ * @param string $url
+ * @return string $cleanurl
+ */
 function clean_url( $url ) {
 	if ('' == $url) return $url;
 	$url = preg_replace('|[^a-z0-9-~+_.?#=&;,/:]|i', '', $url);
@@ -239,6 +276,11 @@
 	return $url;
 }
 
+/**
+ * Returns the amount of comments a post has
+ * @param int $post_id The post to check, defaults to the current global $id
+ * @return int $total The number of comments the post has
+ */
 function get_comments_number( $post_id = 0 ) {
 	global $wpdb, $comment_count_cache, $id;
 	$post_id = (int) $post_id;
@@ -252,6 +294,14 @@
 	return apply_filters('get_comments_number', $comment_count_cache[$post_id]);
 }
 
+/**
+ * Echoes the language string for the number of comments the current global post $id has.
+ * Default language is english.
+ * @param string $zero String representing no comments
+ * @param string $one String representing 1 comment
+ * @param string $more String representing '%' comments.
+ * @param string $number Defunct.
+ */
 function comments_number( $zero = 'No Comments', $one = '1 Comment', $more = '% Comments', $number = '' ) {
 	global $id, $comment;
 	$number = get_comments_number( $id );
@@ -265,19 +315,36 @@
 	echo apply_filters('comments_number', $blah);
 }
 
+/**
+ * Returns the link to the current working posts' comments
+ * @return string $postcommentslink
+ */
 function get_comments_link() {
 	return get_permalink() . '#comments';
 }
 
+/**
+ * Returns the link to the current working comment
+ * @return string $commentlink
+ */
 function get_comment_link() {
 	global $comment;
 	return get_permalink( $comment->comment_post_ID ) . '#comment-' . $comment->comment_ID;
 }
 
+/**
+ * Echoes the link to the current working posts' comments
+ */
 function comments_link( $file = '', $echo = true ) {
     echo get_comments_link();
 }
 
+/**
+ * Echoes the JS popup script to show a comment
+ * @param int $width Window width. Default is 400
+ * @param int $height Window height. Default is 400
+ * @param string $file The file to display. Defaults to index
+ */
 function comments_popup_script($width=400, $height=400, $file='') {
     global $wpcommentspopupfile, $wptrackbackpopupfile, $wppingbackpopupfile, $wpcommentsjavascript;
 
@@ -292,6 +359,15 @@
     echo $javascript;
 }
 
+/**
+ * Echoes the link to the popup window of comments for the current global post $id.
+ * Default language is english.
+ * @param string $zero String representing no comments
+ * @param string $one String representing 1 comment
+ * @param string $more String representing '%' comments.
+ * @param string $CSSclass The css class to assign the link
+ * @param string $none String representing comments off
+ */
 function comments_popup_link($zero='No Comments', $one='1 Comment', $more='% Comments', $CSSclass='', $none='Comments Off') {
 	global $id, $wpcommentspopupfile, $wpcommentsjavascript, $post, $wpdb;
 	global $comment_count_cache;
@@ -336,16 +412,24 @@
 	}
 	}
 }
-
+/**
+ * Returns the comment id of the current global $comment
+ * @return int $commentid
+ */
 function get_comment_ID() {
 	global $comment;
 	return apply_filters('get_comment_ID', $comment->comment_ID);
 }
-
+/**
+ * Echoes the comment id of the current global $comment
+ */
 function comment_ID() {
 	echo get_comment_ID();
 }
-
+/**
+ * Returns the author of the current global $comment
+ * @return string $commentauthor
+ */
 function get_comment_author() {
 	global $comment;
 	if ( empty($comment->comment_author) )
@@ -354,21 +438,32 @@
 		$author = $comment->comment_author;
 	return apply_filters('get_comment_author', $author);
 }
-
+/**
+ * Echoes the author of the current global $comment
+ */
 function comment_author() {
 	$author = apply_filters('comment_author', get_comment_author() );
 	echo $author;
 }
-
+/**
+ * Returns the email of the author of the current global $comment
+ * @return string $commentauthoremail
+ */
 function get_comment_author_email() {
 	global $comment;
 	return apply_filters('get_comment_author_email', $comment->comment_author_email);
 }
-
+/**
+ * Echoes the email of the author of the current global $comment
+ */
 function comment_author_email() {
 	echo apply_filters('author_email', get_comment_author_email() );
 }
 
+/**
+ * Returns the html link to the url of the author of the current global $comment
+ * @return string $commentauthorurl
+ */
 function get_comment_author_link() {
 	global $comment;
 	$url    = get_comment_author_url();
@@ -381,10 +476,17 @@
 	return apply_filters('get_comment_author_link', $return);
 }
 
+/**
+ * Echoes the html link to the url of the author of the current global $comment
+ */
 function comment_author_link() {
 	echo get_comment_author_link();
 }
 
+/**
+ * Returns the comment type of the current global $comment
+ * @return string $commenttype
+ */
 function get_comment_type() {
 	global $comment;
 
@@ -394,6 +496,9 @@
 	return apply_filters('get_comment_type', $comment->comment_type);
 }
 
+/**
+ * Echoes the comment type of the current global $comment
+ */
 function comment_type($commenttxt = 'Comment', $trackbacktxt = 'Trackback', $pingbacktxt = 'Pingback') {
 	$type = get_comment_type();
 	switch( $type ) {
@@ -408,15 +513,25 @@
 	}
 }
 
+/**
+ * Returns the url of the author of the current global $comment
+ * @return string $commenttype
+ */
 function get_comment_author_url() {
 	global $comment;
 	return apply_filters('get_comment_author_url', $comment->comment_author_url);
 }
 
+/**
+ * Echoes the url of the author of the current global $comment
+ */
 function comment_author_url() {
 	echo apply_filters('comment_url', get_comment_author_url());
 }
 
+/**
+ * Echoes the html email link to the author of the current global $comment
+ */
 function comment_author_email_link($linktext='', $before='', $after='') {
 	global $comment;
 	$email = apply_filters('comment_email', $comment->comment_author_email);
@@ -428,6 +543,14 @@
 	}
 }
 
+/**
+ * Returns the HTML link of the url of the author of the current global $comment,
+ * encased in any pre or post text.
+ * @param string $linktext Text to put in the link. Defaults to the URL
+ * @param string $before Text to come before the link
+ * @param string $after Text to come after the link
+ * @return string $link The html link sandwiched between the $before and $after params
+ */
 function get_comment_author_url_link( $linktext = '', $before = '', $after = '' ) {
 	global $comment;
 	$url = get_comment_author_url();
@@ -436,28 +559,48 @@
 	return apply_filters('get_comment_author_url_link', $return);
 }
 
+/**
+ * Echoss the HTML link of the url of the author of the current global $comment,
+ * encased in any pre or post text.
+ * @param string $linktext Text to put in the link. Defaults to the URL
+ * @param string $before Text to come before the link
+ * @param string $after Text to come after the link
+ */
 function comment_author_url_link( $linktext = '', $before = '', $after = '' ) {
 	echo get_comment_author_url_link( $linktext, $before, $after );
 }
-
+/**
+ * Returns the IP address of the author of the current global $comment
+ * @return string $ipaddress
+ */
 function get_comment_author_IP() {
 	global $comment;
 	return apply_filters('get_comment_author_IP', $comment->comment_author_IP);
 }
-
+/**
+ * Echoes the IP address of the author of the current global $comment
+ */
 function comment_author_IP() {
 	echo get_comment_author_IP();
 }
-
+/**
+ * Returns the text of the current global $comment
+ * @return string $text
+ */
 function get_comment_text() {
 	global $comment;
 	return apply_filters('get_comment_text', $comment->comment_content);
 }
-
+/**
+ * Echoes the text of the current global $comment
+ */
 function comment_text() {
 	echo apply_filters('comment_text', get_comment_text() );
 }
-
+/**
+ * Returns the excerpt of the current global $comment
+ * @return string $excerpt
+ */
 function get_comment_excerpt() {
 	global $comment;
 	$comment_text = strip_tags($comment->comment_content);
@@ -476,11 +619,17 @@
 	$excerpt .= ($use_dotdotdot) ? '...' : '';
 	return apply_filters('get_comment_excerpt', $excerpt);
 }
-
+/**
+ * Echoes the excerpt of the current global $comment
+ */
 function comment_excerpt() {
 	echo apply_filters('comment_excerpt', get_comment_excerpt() );
 }
-
+/**
+ * Returns the comment date of the current global $comment
+ * @param string $d The format of the date (defaults to user's config)
+ * @return string $date The formatted date
+ */
 function get_comment_date( $d = '' ) {
 	global $comment;
 	if ( '' == $d )
@@ -489,11 +638,19 @@
 		$date = mysql2date($d, $comment->comment_date);
 	return apply_filters('get_comment_date', $date);
 }
-
+/**
+ * Echoes the comment date of the current global $comment
+ * @param string $d The format of the date (defaults to user's config)
+ */
 function comment_date( $d = '' ) {
 	echo get_comment_date( $d );
 }
-
+/**
+ * Returns the comment time of the current global $comment
+ * @param string $d The format of the time (defaults to user's config)
+ * @param boolean $gmt Whether to put the date into GMT
+ * @return string $time The formatted time
+ */
 function get_comment_time( $d = '', $gmt = false ) {
 	global $comment;
 	$comment_date = $gmt? $comment->comment_date_gmt : $comment->comment_date;
@@ -503,11 +660,17 @@
 		$date = mysql2date($d, $comment_date);
 	return apply_filters('get_comment_time', $date);
 }
-
+/**
+ * Echoes the comment time of the current global $comment
+ * @param string $d The format of the time (defaults to user's config)
+ */
 function comment_time( $d = '' ) {
 	echo get_comment_time($d);
 }
-
+/**
+ * Returns the current global $post's trackback URL
+ * @return string $url
+ */
 function get_trackback_url() {
 	global $id;
 	$tb_url = get_settings('siteurl') . '/wp-trackback.php?p=' . $id;
@@ -517,13 +680,21 @@
 
 	return $tb_url;
 }
+/**
+ * Echoes or returns the current global $post's trackback URL
+ * @param boolean $display Whether to display or echo
+ * @return mixed $ret void if echoing, string URL if returning
+ */
 function trackback_url( $display = true ) {
 	if ( $display)
 		echo get_trackback_url();
 	else
 		return get_trackback_url();
 }
-
+/**
+ * Generates and echoes the RDF for the trackback information of current global $post
+ * @param int $timezone
+ */
 function trackback_rdf($timezone = 0) {
 	global $id;
 	if (!stristr($_SERVER['HTTP_USER_AGENT'], 'W3C_Validator')) {
@@ -541,7 +712,10 @@
 	echo '</rdf:RDF>';
 	}
 }
-
+/**
+ * Returns whether the current global $post is open for comments
+ * @return boolean $open
+ */
 function comments_open() {
 	global $post;
 	if ( 'open' == $post->comment_status )
@@ -549,7 +723,10 @@
 	else
 		return false;
 }
-
+/**
+ * Returns whether the current global $post is open for pings
+ * @return boolean $open
+ */
 function pings_open() {
 	global $post;
 	if ( 'open' == $post->ping_status ) 
@@ -559,7 +736,11 @@
 }
 
 // Non-template functions
-
+/**
+ * Returns the date the last comment was modified
+ * @param string $timezone Timezone to apply date to ('server'|'blog'|'gmt')
+ * @return string $date
+ */
 function get_lastcommentmodified($timezone = 'server') {
 	global $cache_lastcommentmodified, $pagenow, $wpdb;
 	$add_seconds_blog = get_settings('gmt_offset') * 3600;
@@ -583,7 +764,13 @@
 	}
 	return $lastcommentmodified;
 }
-
+/**
+ * Returns an array of comment data about comment $comment_ID
+ * @param int $comment_ID
+ * @param int $no_cache Whether info is in global $postc object or not
+ * @param boolean $include_unapparoved Whether to retrieve unapproved comments
+ * @return mixed $ret array of information on success, false on failure
+ */
 function get_commentdata( $comment_ID, $no_cache = 0, $include_unapproved = false ) { // less flexible, but saves DB queries
 	global $postc, $id, $commentdata, $wpdb;
 	if ($no_cache) {
@@ -607,7 +794,11 @@
 	}
 	return $myrow;
 }
-
+/**
+ * Pings back the links found in a post
+ * @param string $content Content of post
+ * @param int $post_ID The id of the post
+ */
 function pingback($content, $post_ID) {
 	global $wp_version, $wpdb;
 	include_once (ABSPATH . WPINC . '/class-IXR.php');
@@ -687,7 +878,12 @@
 	debug_fwrite($log, "\nEND: ".time()."\n****************************\n");
 	debug_fclose($log);
 }
-
+/**
+ * Finds a pingback server URI based on the given URL
+ * @param string $url URL to ping
+ * @param int $timeout_bytes Number of bytes to timeout at. Prevents big file downloads, default is 2048.
+ * @return mixed $ret False on failure, string containing URI on success.
+ */
 function discover_pingback_server_uri($url, $timeout_bytes = 2048) {
 	global $wp_version;
 
@@ -777,7 +973,11 @@
 	// We didn't find anything.
 	return false;
 }
-
+/**
+ * Checks whether an attachment is hosted locally
+ * @param string $url URL of the attachment
+ * @return boolean $is_local Whether the attachment is local
+ */
 function is_local_attachment($url) {
 	if ( !strstr($url, get_bloginfo('home') ) )
 		return false;
@@ -790,7 +990,12 @@
 	}
 	return false;
 }
-
+/**
+ * Sets the status of comment $comment_id to $comment_status
+ * @param int $comment_id
+ * @param string $comment_status 'hold' | 'approve' | 'spam' | 'delete'
+ * @return boolean $success Whether the operation performed successfully
+ */
 function wp_set_comment_status($comment_id, $comment_status) {
     global $wpdb;
 
@@ -824,7 +1029,11 @@
 		return false;
     }
 }
-
+/**
+ * Returns the status of a comment $comment_id
+ * @param int $comment_id
+ * @return mixed $status 'deleted' | 'approved' | 'unapproved' | 'spam' | false
+ */
 function wp_get_comment_status($comment_id) {
 	global $wpdb;
 
@@ -841,7 +1050,17 @@
 		return false;
 	}
 }
-
+/**
+ * Checks whether a comment passes internal checks to be allowed to add
+ * @param string $author
+ * @param string $email
+ * @param string $url
+ * @param string $comment
+ * @param string $user_ip
+ * @param string $user_agent
+ * @param string $comment_type 'comment' | 'trackback' | 'pingback'
+ * @return boolean $allowed
+ */
 function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $comment_type) {
 	global $wpdb;
 
@@ -899,7 +1118,11 @@
 
 	return true;
 }
-
+/**
+ * Returns the approved comments for post $post_id
+ * @param int $post_id
+ * @return array $comments The approved comments (objects)
+ */
 function get_approved_comments($post_id) {
 	global $wpdb;
 	return $wpdb->get_results("SELECT * FROM $wpdb->comments WHERE comment_post_ID = $post_id AND comment_approved = '1' ORDER BY comment_date");