Ticket #2648: comment-functions.diff

comment-functions.php

@@ -2 +2 @@
 
 // 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 +48 @@
         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 +86 @@
         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 +123 @@
         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 +140 @@
         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 +194 @@
         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 +240 @@
         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 +262 @@
         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 +276 @@
         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 +294 @@
         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 +315 @@
         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 +359 @@
     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 +412 @@
         }
         }
 }
-
+/**
+ * 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 +438 @@
                 $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 +476 @@
         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 +496 @@
         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 +513 @@
         }
 }
 
+/**
+ * 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 +543 @@
         }
 }
 
+/**
+ * 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 +559 @@
         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 +619 @@
         $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 +638 @@
                 $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 +660 @@
                 $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 +680 @@
 
         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 +712 @@
         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 +723 @@
         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 +736 @@
 }
 
 // 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 +764 @@
         }
         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 +794 @@
         }
         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 +878 @@
         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 +973 @@
         // 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 +990 @@
         }
         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 +1029 @@
                 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 +1050 @@
                 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 +1118 @@
 
         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");