Index: comment.php =================================================================== --- comment.php (revision 6543) +++ comment.php (working copy) @@ -1,5 +1,27 @@ get_results($wpdb->prepare("SELECT * FROM $wpdb->comments WHERE comment_post_ID = %d AND comment_approved = '1' ORDER BY comment_date", $post_id)); } - -// Retrieves comment data given a comment ID or comment object. -// Handles comment caching. +/** + * get_comment() - Retrieves comment data given a comment ID or comment object. + * + * {@internal Missing Long Description}} + * + * @since 2.0 + * @uses $wpdb + * + * @param object|string|int $comment {@internal Missing Description}} + * @param string $output OBJECT or ARRAY_A or ARRAY_N constants + * @return object|array|null Depends on $output value. + */ function &get_comment(&$comment, $output = OBJECT) { global $wpdb; @@ -102,8 +141,27 @@ } } - -// Deprecate in favor of get_comment()? +/** + * get_commentdata() - Returns an array of comment data about comment $comment_ID + * + * get_comment() technically does the same thing as this function. This function also + * appears to reference variables and then not use them or not update them when needed. + * It is advised to switch to get_comment(), since this function might be deprecated in + * favor of using get_comment(). + * + * @deprecated Use get_comment() + * @see get_comment() + * @since 0.71 + * + * @uses $postc Comment cache, might not be used any more + * @uses $id + * @uses $wpdb Database Object + * + * @param int $comment_ID The ID of the comment + * @param int $no_cache Whether to use the cache or not (casted to bool) + * @param bool $include_unapproved Whether to include unapproved comments or not + * @return array The comment data + */ function get_commentdata( $comment_ID, $no_cache = 0, $include_unapproved = false ) { // less flexible, but saves DB queries global $postc, $id, $wpdb; if ( $no_cache ) { @@ -127,7 +185,18 @@ return $myrow; } - +/** + * get_lastcommentmodified() - The date the last comment was modified + * + * {@internal Missing Long Description}} + * + * @since 1.5.0 + * @uses $wpdb + * @global array $cache_lastcommentmodified + * + * @param string $timezone Which timezone to use in reference to 'gmt', 'blog', or 'server' locations + * @return string Last comment modified date + */ function get_lastcommentmodified($timezone = 'server') { global $cache_lastcommentmodified, $wpdb; $add_seconds_blog = get_option('gmt_offset') * 3600; @@ -152,54 +221,71 @@ return $lastcommentmodified; } - +/** + * get_comment_count() - The amount of comments in a post or total comments + * + * {@internal Missing Long Description}} + * + * @since 2.0.0 + * @uses $wpdb + * + * @param int $post_id Optional. Comment amount in post if > 0, else total comments blog wide + * @return array The amount of spam, approved, awaiting moderation, and total + */ function get_comment_count( $post_id = 0 ) { - global $wpdb; + global $wpdb; - $post_id = (int) $post_id; + $post_id = (int) $post_id; - $where = ''; - if ( $post_id > 0 ) { - $where = "WHERE comment_post_ID = {$post_id}"; - } + $where = ''; + if ( $post_id > 0 ) { + $where = "WHERE comment_post_ID = {$post_id}"; + } - $totals = (array) $wpdb->get_results(" - SELECT comment_approved, COUNT( * ) AS total - FROM {$wpdb->comments} - {$where} - GROUP BY comment_approved - ", ARRAY_A); + $totals = (array) $wpdb->get_results(" + SELECT comment_approved, COUNT( * ) AS total + FROM {$wpdb->comments} + {$where} + GROUP BY comment_approved + ", ARRAY_A); - $comment_count = array( - "approved" => 0, - "awaiting_moderation" => 0, - "spam" => 0, - "total_comments" => 0 - ); + $comment_count = array( + "approved" => 0, + "awaiting_moderation" => 0, + "spam" => 0, + "total_comments" => 0 + ); - foreach ( $totals as $i => $row ) { - switch ( $row['comment_approved'] ) { - case 'spam': - $comment_count['spam'] = $row['total']; - $comment_count["total_comments"] += $row['total']; - break; - case 1: - $comment_count['approved'] = $row['total']; - $comment_count['total_comments'] += $row['total']; - break; - case 0: - $comment_count['awaiting_moderation'] = $row['total']; - $comment_count['total_comments'] += $row['total']; - break; - default: - break; - } - } + foreach ( $totals as $i => $row ) { + switch ( $row['comment_approved'] ) { + case 'spam': + $comment_count['spam'] = $row['total']; + $comment_count["total_comments"] += $row['total']; + break; + case 1: + $comment_count['approved'] = $row['total']; + $comment_count['total_comments'] += $row['total']; + break; + case 0: + $comment_count['awaiting_moderation'] = $row['total']; + $comment_count['total_comments'] += $row['total']; + break; + default: + break; + } + } - return $comment_count; + return $comment_count; } - +/** + * sanitize_comment_cookies() - {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.0.4 + * + */ function sanitize_comment_cookies() { if ( isset($_COOKIE['comment_author_'.COOKIEHASH]) ) { $comment_author = apply_filters('pre_comment_author_name', $_COOKIE['comment_author_'.COOKIEHASH]); @@ -222,7 +308,19 @@ } } - +/** + * wp_allow_comment() - Validates whether this comment is allowed to be made or not + * + * {@internal Missing Long Description}} + * + * @since 2.0.0 + * @uses $wpdb + * @uses apply_filters() Calls 'pre_comment_approved' hook on the type of comment + * @uses do_action() Calls 'check_comment_flood' hook on $comment_author_IP, $comment_author_email, and $comment_date_gmt + * + * @param array $commentdata Contains information on the comment + * @return mixed Signifies the approval status (0|1|'spam') + */ function wp_allow_comment($commentdata) { global $wpdb; extract($commentdata, EXTR_SKIP); @@ -261,6 +359,20 @@ return $approved; } +/** + * check_comment_flood_db() - {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.3.0 + * @uses $wpdb + * @uses apply_filters() {@internal Missing Description}} + * @uses do_action() {@internal Missing Description}} + * + * @param string $ip {@internal Missing Description}} + * @param string $email {@internal Missing Description}} + * @param unknown_type $date {@internal Missing Description}} + */ function check_comment_flood_db( $ip, $email, $date ) { global $wpdb; if ( $lasttime = $wpdb->get_var("SELECT comment_date_gmt FROM $wpdb->comments WHERE comment_author_IP = '$ip' OR comment_author_email = '$email' ORDER BY comment_date DESC LIMIT 1") ) { @@ -274,6 +386,22 @@ } } +/** + * wp_blacklist_check() - Does comment contain blacklisted characters or words + * + * {@internal Missing Long Description}} + * + * @since 1.5.0 + * @uses do_action() Calls 'wp_blacklist_check' hook for all parameters + * + * @param string $author The author of the comment + * @param string $email The email of the comment + * @param string $url The url used in the comment + * @param string $comment The comment content + * @param string $user_ip The comment author IP address + * @param string $user_agent The author's browser user agent + * @return bool True if comment contains blacklisted content, false if comment does not + */ function wp_blacklist_check($author, $email, $url, $comment, $user_ip, $user_agent) { do_action('wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent); @@ -316,7 +444,20 @@ return false; } - +/** + * wp_delete_comment() - Removes comment ID and maybe updates post comment count + * + * The post comment count will be updated if the comment was approved and has a post + * ID available. + * + * @since 2.0.0 + * @uses $wpdb + * @uses do_action() Calls 'delete_comment' hook on comment ID + * @uses do_action() Calls 'wp_set_comment_status' hook on comment ID with 'delete' set for the second parameter + * + * @param int $comment_id Comment ID + * @return bool False if delete comment query failure, true on success + */ function wp_delete_comment($comment_id) { global $wpdb; do_action('delete_comment', $comment_id); @@ -336,7 +477,14 @@ return true; } - +/** + * wp_get_comment_status() - The status of a comment by ID + * + * @since 1.0.0 + * + * @param int $comment_id Comment ID + * @return string|bool Status might be 'deleted', 'approved', 'unapproved', 'spam'. False on failure + */ function wp_get_comment_status($comment_id) { $comment = get_comment($comment_id); if ( !$comment ) @@ -356,7 +504,18 @@ return false; } - +/** + * wp_get_current_commenter() - Get current commenter's name, email, and URL + * + * Expects cookies content to already be sanitized. User of this function + * might wish to recheck the returned array for validity. + * + * @see sanitize_comment_cookies() Use to sanitize cookies + * + * @since 2.0.4 + * + * @return array Comment author, email, url respectively + */ function wp_get_current_commenter() { // Cookies should already be sanitized. @@ -375,7 +534,17 @@ return compact('comment_author', 'comment_author_email', 'comment_author_url'); } - +/** + * wp_insert_comment() - Inserts a comment to the database + * + * {@internal Missing Long Description}} + * + * @since 2.0.0 + * @uses $wpdb + * + * @param array $commentdata Contains information on the comment + * @return int The new comment's id + */ function wp_insert_comment($commentdata) { global $wpdb; extract($commentdata, EXTR_SKIP); @@ -407,7 +576,25 @@ return $id; } - +/** + * wp_filter_comment() - Parses and returns comment information + * + * Sets the comment data 'filtered' field to true when finished. This + * can be checked as to whether the comment should be filtered and to + * keep from filtering the same comment more than once. + * + * @since 2.0.0 + * @uses apply_filters() Calls 'pre_user_id' hook on comment author's user ID + * @uses apply_filters() Calls 'pre_comment_user_agent' hook on comment author's user agent + * @uses apply_filters() Calls 'pre_comment_author_name' hook on comment author's name + * @uses apply_filters() Calls 'pre_comment_content' hook on the comment's content + * @uses apply_filters() Calls 'pre_comment_user_ip' hook on comment author's IP + * @uses apply_filters() Calls 'pre_comment_author_url' hook on comment author's URL + * @uses apply_filters() Calls 'pre_comment_author_email' hook on comment author's email address + * + * @param array $commentdata Contains information on the comment + * @return array 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']); @@ -420,7 +607,18 @@ return $commentdata; } - +/** + * wp_throttle_comment_flood() - {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.1.0 + * + * @param unknown_type $block {@internal Missing Description}} + * @param unknown_type $time_lastcomment {@internal Missing Description}} + * @param unknown_type $time_newcomment {@internal Missing Description}} + * @return unknown {@internal Missing Description}} + */ function wp_throttle_comment_flood($block, $time_lastcomment, $time_newcomment) { if ( $block ) // a plugin has already blocked... we'll let that decision stand return $block; @@ -429,7 +627,21 @@ return false; } - +/** + * wp_new_comment() - Parses and adds a new comment to the database + * + * {@internal Missing Long Description}} + * + * @since 1.5.0 + * @uses apply_filters() Calls 'preprocess_comment' hook on $commentdata parameter array before processing + * @uses do_action() Calls 'comment_post' hook on $comment_ID returned from adding the comment and if the comment was approved. + * @uses wp_filter_comment() Used to filter comment before adding comment + * @uses wp_allow_comment() checks to see if comment is approved. + * @uses wp_insert_comment() Does the actual comment insertion to the database + * + * @param array $commentdata Contains information on the comment + * @return int The ID of the comment after adding. + */ function wp_new_comment( $commentdata ) { $commentdata = apply_filters('preprocess_comment', $commentdata); @@ -463,7 +675,17 @@ return $comment_ID; } - +/** + * wp_set_comment_status() - Sets the status of comment ID + * + * {@internal Missing Long Description}} + * + * @since 1.0.0 + * + * @param int $comment_id Comment ID + * @param string $comment_status New comment status, either 'hold', 'approve', 'spam', or 'delete' + * @return bool False on failure or deletion and true on success. + */ function wp_set_comment_status($comment_id, $comment_status) { global $wpdb; @@ -496,7 +718,17 @@ return true; } - +/** + * wp_update_comment() - Parses and updates an existing comment in the database + * + * {@internal Missing Long Description}} + * + * @since 2.0.0 + * @uses $wpdb + * + * @param array $commentarr Contains information on the comment + * @return int Comment was updated if value is 1, or was not updated if value is 0. + */ function wp_update_comment($commentarr) { global $wpdb; @@ -538,19 +770,51 @@ return $rval; } -function wp_defer_comment_counting($defer=NULL) { +/** + * wp_defer_comment_counting() - Whether to defer comment counting + * + * When setting $defer to true, all post comment counts will not be updated + * until $defer is set to false. When $defer is set to false, then all + * previously deferred updated post comment counts will then be automatically + * updated without having to call wp_update_comment_count() after. + * + * @since 2.5 + * @staticvar bool $_defer + * + * @param bool $defer + * @return unknown + */ +function wp_defer_comment_counting($defer=null) { static $_defer = false; if ( is_bool($defer) ) { $_defer = $defer; // flush any deferred counts if ( !$defer ) - wp_update_comment_count( NULL, true ); + wp_update_comment_count( null, true ); } return $_defer; } +/** + * wp_update_comment_count() - Updates the comment count for post(s) + * + * When $do_deferred is false (is by default) and the comments have been + * set to be deferred, the post_id will be added to a queue, which will + * be updated at a later date and only updated once per post ID. + * + * If the comments have not be set up to be deferred, then the post will + * be updated. When $do_deferred is set to true, then all previous deferred + * post IDs will be updated along with the current $post_id. + * + * @since 2.1.0 + * @see wp_update_comment_count_now() For what could cause a false return value + * + * @param int $post_id Post ID + * @param bool $do_deferred Whether to process previously deferred post comment counts + * @return bool True on success, false on failure + */ function wp_update_comment_count($post_id, $do_deferred=false) { static $_deferred = array(); @@ -558,7 +822,7 @@ $_deferred = array_unique($_deferred); foreach ( $_deferred as $i => $_post_id ) { wp_update_comment_count_now($_post_id); - unset( $_deferred[$i] ); + unset( $_deferred[$i] ); /** @todo Move this outside of the foreach and reset $_deferred to an array instead */ } } @@ -572,6 +836,17 @@ } +/** + * wp_update_comment_count_now() - Updates the comment count for the post + * + * @since 2.5 + * @uses $wpdb + * @uses do_action() Calls 'wp_update_comment_count' hook on $post_id, $new, and $old + * @uses do_action() Calls 'edit_posts' hook on $post_id and $post + * + * @param int $post_id Post ID + * @return bool False on '0' $post_id or if post with ID does not exist. True on success. + */ function wp_update_comment_count_now($post_id) { global $wpdb; $post_id = (int) $post_id; @@ -595,11 +870,22 @@ return true; } - // // Ping and trackback functions. // +/** + * discover_pingback_server_uri() - Finds a pingback server URI based on the given URL + * + * {@internal Missing Long Description}} + * + * @since 1.5.0 + * @uses $wp_version + * + * @param string $url URL to ping + * @param int $timeout_bytes Number of bytes to timeout at. Prevents big file downloads, default is 2048. + * @return bool|string False on failure, string containing URI on success. + */ function discover_pingback_server_uri($url, $timeout_bytes = 2048) { global $wp_version; @@ -681,7 +967,14 @@ return false; } - +/** + * do_all_pings() - {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.1.0 + * @uses $wpdb + */ function do_all_pings() { global $wpdb; @@ -708,6 +1001,16 @@ generic_ping(); } +/** + * do_trackbacks() - {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 1.5.0 + * @uses $wpdb + * + * @param int $post_id Post ID to do trackbacks on + */ function do_trackbacks($post_id) { global $wpdb; @@ -746,7 +1049,16 @@ } } - +/** + * generic_ping() - {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 1.2.0 + * + * @param int $post_id Post ID. Not actually used. + * @return int Same as Post ID from parameter + */ function generic_ping($post_id = 0) { $services = get_option('ping_sites'); $services = preg_replace("|(\s)+|", '$1', $services); // Kill dupe lines @@ -760,7 +1072,18 @@ return $post_id; } - +/** + * pingback() - Pings back the links found in a post + * + * {@internal Missing Long Description}} + * + * @since 0.71 + * @uses $wp_version + * @uses IXR_Client + * + * @param string $content {@internal Missing Description}} + * @param int $post_ID {@internal Missing Description}} + */ function pingback($content, $post_ID) { global $wp_version; include_once(ABSPATH . WPINC . '/class-IXR.php'); @@ -826,7 +1149,16 @@ } } - +/** + * privacy_ping_filter() - {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.1.0 + * + * @param unknown_type $sites {@internal Missing Description}} + * @return unknown {@internal Missing Description}} + */ function privacy_ping_filter($sites) { if ( '0' != get_option('blog_public') ) return $sites; @@ -834,7 +1166,21 @@ return ''; } -// Send a Trackback +/** + * trackback() - Send a Trackback + * + * {@internal Missing Long Description}} + * + * @since 0.71 + * @uses $wpdb + * @uses $wp_version WordPress version + * + * @param string $trackback_url {@internal Missing Description}} + * @param string $title {@internal Missing Description}} + * @param string $excerpt {@internal Missing Description}} + * @param int $ID {@internal Missing Description}} + * @return unknown {@internal Missing Description}} + */ function trackback($trackback_url, $title, $excerpt, $ID) { global $wpdb, $wp_version; @@ -866,7 +1212,18 @@ return $wpdb->query("UPDATE $wpdb->posts SET to_ping = TRIM(REPLACE(to_ping, '$tb_url', '')) WHERE ID = '$ID'"); } - +/** + * weblog_ping() - {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 1.2.0 + * @uses $wp_version + * @uses IXR_Client + * + * @param unknown_type $server + * @param unknown_type $path + */ function weblog_ping($server = '', $path = '') { global $wp_version; include_once(ABSPATH . WPINC . '/class-IXR.php'); @@ -887,12 +1244,34 @@ // Cache // +/** + * clean_comment_cache() - Removes comment ID from the comment cache + * + * @since 2.3.0 + * @package WordPress + * @subpackage Cache + * + * @param int $id Comment ID to remove from cache + */ function clean_comment_cache($id) { wp_cache_delete($id, 'comment'); } +/** + * update_comment_cache() - Updates the comment cache of given comments + * + * Will add the comments in $comments to the cache. If comment ID already + * exists in the comment cache then it will not be updated. + * + * The comment is added to the cache using the comment group with the key + * using the ID of the comments. + * + * @since 2.3.0 + * + * @param array $comments Array of comment row objects + */ function update_comment_cache($comments) { - foreach ( $comments as $comment ) + foreach ( $comments as $comment ) /** @todo Add "(array)" type cast before $comments to prevent warning */ wp_cache_add($comment->comment_ID, $comment, 'comment'); }