WordPress.org
Get WordPress

Make WordPress Core

Ticket #5578: comment.phpdoc.r6544.diff

File comment.phpdoc.r6544.diff, 21.6 KB (added by darkdragon, 18 years ago)

Incomplete documentation for comment.php based off or r6544

  • comment.php

     
    11<?php
     2/**
     3 * Manages WordPress comments
     4 *
     5 * @package WordPress
     6 */
    27
     8/**
     9 * check_comment() - Checks whether a comment passes internal checks to be allowed to add
     10 *
     11 * {@internal Missing Long Description}}
     12 *
     13 * @since 1.2
     14 * @uses $wpdb
     15 *
     16 * @param string $author {@internal Missing Description }}
     17 * @param string $email {@internal Missing Description }}
     18 * @param string $url {@internal Missing Description }}
     19 * @param string $comment {@internal Missing Description }}
     20 * @param string $user_ip {@internal Missing Description }}
     21 * @param string $user_agent {@internal Missing Description }}
     22 * @param string $comment_type {@internal Missing Description }}
     23 * @return bool {@internal Missing Description }}
     24 */
    325function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $comment_type) {
    426        global $wpdb;
    527
    … …  
    6082        return true;
    6183}
    6284
    63 
     85/**
     86 * get_approved_comments() - Returns the approved comments for post $post_id
     87 *
     88 * @since 2.0
     89 * @uses $wpdb
     90 *
     91 * @param int $post_id The ID of the post
     92 * @return array $comments The approved comments
     93 */
    6494function get_approved_comments($post_id) {
    6595        global $wpdb;
    6696        return $wpdb->get_results($wpdb->prepare("SELECT * FROM $wpdb->comments WHERE comment_post_ID = %d AND comment_approved = '1' ORDER BY comment_date", $post_id));
    6797}
    6898
    69 
    70 // Retrieves comment data given a comment ID or comment object.
    71 // Handles comment caching.
     99/**
     100 * get_comment() - Retrieves comment data given a comment ID or comment object.
     101 *
     102 * {@internal Missing Long Description}}
     103 *
     104 * @since 2.0
     105 * @uses $wpdb
     106 *
     107 * @param object|string|int $comment {@internal Missing Description}}
     108 * @param string $output OBJECT or ARRAY_A or ARRAY_N constants
     109 * @return object|array|null Depends on $output value.
     110 */
    72111function &get_comment(&$comment, $output = OBJECT) {
    73112        global $wpdb;
    74113
    … …  
    102141        }
    103142}
    104143
    105 
    106 // Deprecate in favor of get_comment()?
     144/**
     145 * get_commentdata() - Returns an array of comment data about comment $comment_ID
     146 *
     147 * get_comment() technically does the same thing as this function. This function also
     148 * appears to reference variables and then not use them or not update them when needed.
     149 * It is advised to switch to get_comment(), since this function might be deprecated in
     150 * favor of using get_comment().
     151 *
     152 * @deprecated Use get_comment()
     153 * @see get_comment()
     154 * @since 0.71
     155 *
     156 * @uses $postc Comment cache, might not be used any more
     157 * @uses $id
     158 * @uses $wpdb Database Object
     159 *
     160 * @param int $comment_ID The ID of the comment
     161 * @param int $no_cache Whether to use the cache or not (casted to bool)
     162 * @param bool $include_unapproved Whether to include unapproved comments or not
     163 * @return array The comment data
     164 */
    107165function get_commentdata( $comment_ID, $no_cache = 0, $include_unapproved = false ) { // less flexible, but saves DB queries
    108166        global $postc, $id, $wpdb;
    109167        if ( $no_cache ) {
    … …  
    127185        return $myrow;
    128186}
    129187
    130 
     188/**
     189 * get_lastcommentmodified() - The date the last comment was modified
     190 *
     191 * {@internal Missing Long Description}}
     192 *
     193 * @since 1.5.0
     194 * @uses $wpdb
     195 * @global array $cache_lastcommentmodified
     196 *
     197 * @param string $timezone Which timezone to use in reference to 'gmt', 'blog', or 'server' locations
     198 * @return string Last comment modified date
     199 */
    131200function get_lastcommentmodified($timezone = 'server') {
    132201        global $cache_lastcommentmodified, $wpdb;
    133202        $add_seconds_blog = get_option('gmt_offset') * 3600;
    … …  
    152221        return $lastcommentmodified;
    153222}
    154223
    155 
     224/**
     225 * get_comment_count() - The amount of comments in a post or total comments
     226 *
     227 * {@internal Missing Long Description}}
     228 *
     229 * @since 2.0.0
     230 * @uses $wpdb
     231 *
     232 * @param int $post_id Optional. Comment amount in post if > 0, else total comments blog wide
     233 * @return array The amount of spam, approved, awaiting moderation, and total
     234 */
    156235function get_comment_count( $post_id = 0 ) {
    157     global $wpdb;
     236        global $wpdb;
    158237
    159     $post_id = (int) $post_id;
     238        $post_id = (int) $post_id;
    160239
    161     $where = '';
    162     if ( $post_id > 0 ) {
    163         $where = "WHERE comment_post_ID = {$post_id}";
    164     }
     240        $where = '';
     241        if ( $post_id > 0 ) {
     242                $where = "WHERE comment_post_ID = {$post_id}";
     243        }
    165244
    166     $totals = (array) $wpdb->get_results("
    167         SELECT comment_approved, COUNT( * ) AS total
    168         FROM {$wpdb->comments}
    169         {$where}
    170         GROUP BY comment_approved
    171     ", ARRAY_A);
     245        $totals = (array) $wpdb->get_results("
     246                SELECT comment_approved, COUNT( * ) AS total
     247                FROM {$wpdb->comments}
     248                {$where}
     249                GROUP BY comment_approved
     250        ", ARRAY_A);
    172251
    173     $comment_count = array(                         
    174         "approved"              => 0,               
    175         "awaiting_moderation"   => 0,
    176         "spam"                  => 0,
    177         "total_comments"        => 0
    178     );
     252        $comment_count = array(                         
     253                "approved"              => 0,               
     254                "awaiting_moderation"   => 0,
     255                "spam"                  => 0,
     256                "total_comments"        => 0
     257        );
    179258
    180     foreach ( $totals as $i => $row ) {
    181         switch ( $row['comment_approved'] ) {
    182             case 'spam':
    183                 $comment_count['spam'] = $row['total'];
    184                 $comment_count["total_comments"] += $row['total'];
    185                 break;
    186             case 1:
    187                 $comment_count['approved'] = $row['total'];
    188                 $comment_count['total_comments'] += $row['total'];
    189                 break;
    190             case 0:
    191                 $comment_count['awaiting_moderation'] = $row['total'];
    192                 $comment_count['total_comments'] += $row['total'];
    193                 break;
    194             default:
    195                 break;
    196         }
    197     }
     259        foreach ( $totals as $i => $row ) {
     260                switch ( $row['comment_approved'] ) {
     261                        case 'spam':
     262                                $comment_count['spam'] = $row['total'];
     263                                $comment_count["total_comments"] += $row['total'];
     264                                break;
     265                        case 1:
     266                                $comment_count['approved'] = $row['total'];
     267                                $comment_count['total_comments'] += $row['total'];
     268                                break;
     269                        case 0:
     270                                $comment_count['awaiting_moderation'] = $row['total'];
     271                                $comment_count['total_comments'] += $row['total'];
     272                                break;
     273                        default:
     274                                break;
     275                }
     276        }
    198277
    199     return $comment_count;
     278        return $comment_count;
    200279}
    201280
    202 
     281/**
     282 * sanitize_comment_cookies() - {@internal Missing Short Description}}
     283 *
     284 * {@internal Missing Long Description}}
     285 *
     286 * @since 2.0.4
     287 *
     288 */
    203289function sanitize_comment_cookies() {
    204290        if ( isset($_COOKIE['comment_author_'.COOKIEHASH]) ) {
    205291                $comment_author = apply_filters('pre_comment_author_name', $_COOKIE['comment_author_'.COOKIEHASH]);
    … …  
    222308        }
    223309}
    224310
    225 
     311/**
     312 * wp_allow_comment() - Validates whether this comment is allowed to be made or not
     313 *
     314 * {@internal Missing Long Description}}
     315 *
     316 * @since 2.0.0
     317 * @uses $wpdb
     318 * @uses apply_filters() Calls 'pre_comment_approved' hook on the type of comment
     319 * @uses do_action() Calls 'check_comment_flood' hook on $comment_author_IP, $comment_author_email, and $comment_date_gmt
     320 *
     321 * @param array $commentdata Contains information on the comment
     322 * @return mixed Signifies the approval status (0|1|'spam')
     323 */
    226324function wp_allow_comment($commentdata) {
    227325        global $wpdb;
    228326        extract($commentdata, EXTR_SKIP);
    … …  
    261359        return $approved;
    262360}
    263361
     362/**
     363 * check_comment_flood_db() - {@internal Missing Short Description}}
     364 *
     365 * {@internal Missing Long Description}}
     366 *
     367 * @since 2.3.0
     368 * @uses $wpdb
     369 * @uses apply_filters() {@internal Missing Description}}
     370 * @uses do_action() {@internal Missing Description}}
     371 *
     372 * @param string $ip {@internal Missing Description}}
     373 * @param string $email {@internal Missing Description}}
     374 * @param unknown_type $date {@internal Missing Description}}
     375 */
    264376function check_comment_flood_db( $ip, $email, $date ) {
    265377        global $wpdb;
    266378        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") ) {
    … …  
    274386        }
    275387}
    276388
     389/**
     390 * wp_blacklist_check() - Does comment contain blacklisted characters or words
     391 *
     392 * {@internal Missing Long Description}}
     393 *
     394 * @since 1.5.0
     395 * @uses do_action() Calls 'wp_blacklist_check' hook for all parameters
     396 *
     397 * @param string $author The author of the comment
     398 * @param string $email The email of the comment
     399 * @param string $url The url used in the comment
     400 * @param string $comment The comment content
     401 * @param string $user_ip The comment author IP address
     402 * @param string $user_agent The author's browser user agent
     403 * @return bool True if comment contains blacklisted content, false if comment does not
     404 */
    277405function wp_blacklist_check($author, $email, $url, $comment, $user_ip, $user_agent) {
    278406        do_action('wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent);
    279407
    … …  
    316444        return false;
    317445}
    318446
    319 
     447/**
     448 * wp_delete_comment() - Removes comment ID and maybe updates post comment count
     449 *
     450 * The post comment count will be updated if the comment was approved and has a post
     451 * ID available.
     452 *
     453 * @since 2.0.0
     454 * @uses $wpdb
     455 * @uses do_action() Calls 'delete_comment' hook on comment ID
     456 * @uses do_action() Calls 'wp_set_comment_status' hook on comment ID with 'delete' set for the second parameter
     457 *
     458 * @param int $comment_id Comment ID
     459 * @return bool False if delete comment query failure, true on success
     460 */
    320461function wp_delete_comment($comment_id) {
    321462        global $wpdb;
    322463        do_action('delete_comment', $comment_id);
    … …  
    336477        return true;
    337478}
    338479
    339 
     480/**
     481 * wp_get_comment_status() - The status of a comment by ID
     482 *
     483 * @since 1.0.0
     484 *
     485 * @param int $comment_id Comment ID
     486 * @return string|bool Status might be 'deleted', 'approved', 'unapproved', 'spam'. False on failure
     487 */
    340488function wp_get_comment_status($comment_id) {
    341489        $comment = get_comment($comment_id);
    342490        if ( !$comment )
    … …  
    356504                return false;
    357505}
    358506
    359 
     507/**
     508 * wp_get_current_commenter() - Get current commenter's name, email, and URL
     509 *
     510 * Expects cookies content to already be sanitized. User of this function
     511 * might wish to recheck the returned array for validity.
     512 *
     513 * @see sanitize_comment_cookies() Use to sanitize cookies
     514 *
     515 * @since 2.0.4
     516 *
     517 * @return array Comment author, email, url respectively
     518 */
    360519function wp_get_current_commenter() {
    361520        // Cookies should already be sanitized.
    362521
    … …  
    375534        return compact('comment_author', 'comment_author_email', 'comment_author_url');
    376535}
    377536
    378 
     537/**
     538 * wp_insert_comment() - Inserts a comment to the database
     539 *
     540 * {@internal Missing Long Description}}
     541 *
     542 * @since 2.0.0
     543 * @uses $wpdb
     544 *
     545 * @param array $commentdata Contains information on the comment
     546 * @return int The new comment's id
     547 */
    379548function wp_insert_comment($commentdata) {
    380549        global $wpdb;
    381550        extract($commentdata, EXTR_SKIP);
    … …  
    407576        return $id;
    408577}
    409578
    410 
     579/**
     580 * wp_filter_comment() - Parses and returns comment information
     581 *
     582 * Sets the comment data 'filtered' field to true when finished. This
     583 * can be checked as to whether the comment should be filtered and to
     584 * keep from filtering the same comment more than once.
     585 *
     586 * @since 2.0.0
     587 * @uses apply_filters() Calls 'pre_user_id' hook on comment author's user ID
     588 * @uses apply_filters() Calls 'pre_comment_user_agent' hook on comment author's user agent
     589 * @uses apply_filters() Calls 'pre_comment_author_name' hook on comment author's name
     590 * @uses apply_filters() Calls 'pre_comment_content' hook on the comment's content
     591 * @uses apply_filters() Calls 'pre_comment_user_ip' hook on comment author's IP
     592 * @uses apply_filters() Calls 'pre_comment_author_url' hook on comment author's URL
     593 * @uses apply_filters() Calls 'pre_comment_author_email' hook on comment author's email address
     594 *
     595 * @param array $commentdata Contains information on the comment
     596 * @return array Parsed comment information
     597 */
    411598function wp_filter_comment($commentdata) {
    412599        $commentdata['user_id']              = apply_filters('pre_user_id', $commentdata['user_ID']);
    413600        $commentdata['comment_agent']        = apply_filters('pre_comment_user_agent', $commentdata['comment_agent']);
    … …  
    420607        return $commentdata;
    421608}
    422609
    423 
     610/**
     611 * wp_throttle_comment_flood() - {@internal Missing Short Description}}
     612 *
     613 * {@internal Missing Long Description}}
     614 *
     615 * @since 2.1.0
     616 *
     617 * @param unknown_type $block {@internal Missing Description}}
     618 * @param unknown_type $time_lastcomment {@internal Missing Description}}
     619 * @param unknown_type $time_newcomment {@internal Missing Description}}
     620 * @return unknown {@internal Missing Description}}
     621 */
    424622function wp_throttle_comment_flood($block, $time_lastcomment, $time_newcomment) {
    425623        if ( $block ) // a plugin has already blocked... we'll let that decision stand
    426624                return $block;
    … …  
    429627        return false;
    430628}
    431629
    432 
     630/**
     631 * wp_new_comment() - Parses and adds a new comment to the database
     632 *
     633 * {@internal Missing Long Description}}
     634 *
     635 * @since 1.5.0
     636 * @uses apply_filters() Calls 'preprocess_comment' hook on $commentdata parameter array before processing
     637 * @uses do_action() Calls 'comment_post' hook on $comment_ID returned from adding the comment and if the comment was approved.
     638 * @uses wp_filter_comment() Used to filter comment before adding comment
     639 * @uses wp_allow_comment() checks to see if comment is approved.
     640 * @uses wp_insert_comment() Does the actual comment insertion to the database
     641 *
     642 * @param array $commentdata Contains information on the comment
     643 * @return int The ID of the comment after adding.
     644 */
    433645function wp_new_comment( $commentdata ) {
    434646        $commentdata = apply_filters('preprocess_comment', $commentdata);
    435647
    … …  
    463675        return $comment_ID;
    464676}
    465677
    466 
     678/**
     679 * wp_set_comment_status() - Sets the status of comment ID
     680 *
     681 * {@internal Missing Long Description}}
     682 *
     683 * @since 1.0.0
     684 *
     685 * @param int $comment_id Comment ID
     686 * @param string $comment_status New comment status, either 'hold', 'approve', 'spam', or 'delete'
     687 * @return bool False on failure or deletion and true on success.
     688 */
    467689function wp_set_comment_status($comment_id, $comment_status) {
    468690        global $wpdb;
    469691
    … …  
    496718        return true;
    497719}
    498720
    499 
     721/**
     722 * wp_update_comment() - Parses and updates an existing comment in the database
     723 *
     724 * {@internal Missing Long Description}}
     725 *
     726 * @since 2.0.0
     727 * @uses $wpdb
     728 *
     729 * @param array $commentarr Contains information on the comment
     730 * @return int Comment was updated if value is 1, or was not updated if value is 0.
     731 */
    500732function wp_update_comment($commentarr) {
    501733        global $wpdb;
    502734
    … …  
    538770        return $rval;
    539771}
    540772
    541 function wp_defer_comment_counting($defer=NULL) {
     773/**
     774 * wp_defer_comment_counting() - Whether to defer comment counting
     775 *
     776 * When setting $defer to true, all post comment counts will not be updated
     777 * until $defer is set to false. When $defer is set to false, then all
     778 * previously deferred updated post comment counts will then be automatically
     779 * updated without having to call wp_update_comment_count() after.
     780 *
     781 * @since 2.5
     782 * @staticvar bool $_defer
     783 *
     784 * @param bool $defer
     785 * @return unknown
     786 */
     787function wp_defer_comment_counting($defer=null) {
    542788        static $_defer = false;
    543789       
    544790        if ( is_bool($defer) ) {
    545791                $_defer = $defer;
    546792                // flush any deferred counts
    547793                if ( !$defer )
    548                         wp_update_comment_count( NULL, true );
     794                        wp_update_comment_count( null, true );
    549795        }
    550796       
    551797        return $_defer;
    552798}
    553799
     800/**
     801 * wp_update_comment_count() - Updates the comment count for post(s)
     802 *
     803 * When $do_deferred is false (is by default) and the comments have been
     804 * set to be deferred, the post_id will be added to a queue, which will
     805 * be updated at a later date and only updated once per post ID.
     806 *
     807 * If the comments have not be set up to be deferred, then the post will
     808 * be updated. When $do_deferred is set to true, then all previous deferred
     809 * post IDs will be updated along with the current $post_id.
     810 *
     811 * @since 2.1.0
     812 * @see wp_update_comment_count_now() For what could cause a false return value
     813 *
     814 * @param int $post_id Post ID
     815 * @param bool $do_deferred Whether to process previously deferred post comment counts
     816 * @return bool True on success, false on failure
     817 */
    554818function wp_update_comment_count($post_id, $do_deferred=false) {
    555819        static $_deferred = array();
    556820       
    … …  
    558822                $_deferred = array_unique($_deferred);
    559823                foreach ( $_deferred as $i => $_post_id ) {
    560824                        wp_update_comment_count_now($_post_id);
    561                         unset( $_deferred[$i] );
     825                        unset( $_deferred[$i] ); /** @todo Move this outside of the foreach and reset $_deferred to an array instead */
    562826                }
    563827        }
    564828       
    … …  
    572836               
    573837}
    574838
     839/**
     840 * wp_update_comment_count_now() - Updates the comment count for the post
     841 *
     842 * @since 2.5
     843 * @uses $wpdb
     844 * @uses do_action() Calls 'wp_update_comment_count' hook on $post_id, $new, and $old
     845 * @uses do_action() Calls 'edit_posts' hook on $post_id and $post
     846 *
     847 * @param int $post_id Post ID
     848 * @return bool False on '0' $post_id or if post with ID does not exist. True on success.
     849 */
    575850function wp_update_comment_count_now($post_id) {
    576851        global $wpdb;
    577852        $post_id = (int) $post_id;
    … …  
    595870        return true;
    596871}
    597872
    598 
    599873//
    600874// Ping and trackback functions.
    601875//
    602876
     877/**
     878 * discover_pingback_server_uri() - Finds a pingback server URI based on the given URL
     879 *
     880 * {@internal Missing Long Description}}
     881 *
     882 * @since 1.5.0
     883 * @uses $wp_version
     884 *
     885 * @param string $url URL to ping
     886 * @param int $timeout_bytes Number of bytes to timeout at. Prevents big file downloads, default is 2048.
     887 * @return bool|string False on failure, string containing URI on success.
     888 */
    603889function discover_pingback_server_uri($url, $timeout_bytes = 2048) {
    604890        global $wp_version;
    605891
    … …  
    681967        return false;
    682968}
    683969
    684 
     970/**
     971 * do_all_pings() - {@internal Missing Short Description}}
     972 *
     973 * {@internal Missing Long Description}}
     974 *
     975 * @since 2.1.0
     976 * @uses $wpdb
     977 */
    685978function do_all_pings() {
    686979        global $wpdb;
    687980
    … …  
    7081001        generic_ping();
    7091002}
    7101003
     1004/**
     1005 * do_trackbacks() - {@internal Missing Short Description}}
     1006 *
     1007 * {@internal Missing Long Description}}
     1008 *
     1009 * @since 1.5.0
     1010 * @uses $wpdb
     1011 *
     1012 * @param int $post_id Post ID to do trackbacks on
     1013 */
    7111014function do_trackbacks($post_id) {
    7121015        global $wpdb;
    7131016
    … …  
    7461049        }
    7471050}
    7481051
    749 
     1052/**
     1053 * generic_ping() - {@internal Missing Short Description}}
     1054 *
     1055 * {@internal Missing Long Description}}
     1056 *
     1057 * @since 1.2.0
     1058 *
     1059 * @param int $post_id Post ID. Not actually used.
     1060 * @return int Same as Post ID from parameter
     1061 */
    7501062function generic_ping($post_id = 0) {
    7511063        $services = get_option('ping_sites');
    7521064        $services = preg_replace("|(\s)+|", '$1', $services); // Kill dupe lines
    … …  
    7601072        return $post_id;
    7611073}
    7621074
    763 
     1075/**
     1076 * pingback() - Pings back the links found in a post
     1077 *
     1078 * {@internal Missing Long Description}}
     1079 *
     1080 * @since 0.71
     1081 * @uses $wp_version
     1082 * @uses IXR_Client
     1083 *
     1084 * @param string $content {@internal Missing Description}}
     1085 * @param int $post_ID {@internal Missing Description}}
     1086 */
    7641087function pingback($content, $post_ID) {
    7651088        global $wp_version;
    7661089        include_once(ABSPATH . WPINC . '/class-IXR.php');
    … …  
    8261149        }
    8271150}
    8281151
    829 
     1152/**
     1153 * privacy_ping_filter() - {@internal Missing Short Description}}
     1154 *
     1155 * {@internal Missing Long Description}}
     1156 *
     1157 * @since 2.1.0
     1158 *
     1159 * @param unknown_type $sites {@internal Missing Description}}
     1160 * @return unknown {@internal Missing Description}}
     1161 */
    8301162function privacy_ping_filter($sites) {
    8311163        if ( '0' != get_option('blog_public') )
    8321164                return $sites;
    … …  
    8341166                return '';
    8351167}
    8361168
    837 // Send a Trackback
     1169/**
     1170 * trackback() - Send a Trackback
     1171 *
     1172 * {@internal Missing Long Description}}
     1173 *
     1174 * @since 0.71
     1175 * @uses $wpdb
     1176 * @uses $wp_version WordPress version
     1177 *
     1178 * @param string $trackback_url {@internal Missing Description}}
     1179 * @param string $title {@internal Missing Description}}
     1180 * @param string $excerpt {@internal Missing Description}}
     1181 * @param int $ID {@internal Missing Description}}
     1182 * @return unknown {@internal Missing Description}}
     1183 */
    8381184function trackback($trackback_url, $title, $excerpt, $ID) {
    8391185        global $wpdb, $wp_version;
    8401186
    … …  
    8661212        return $wpdb->query("UPDATE $wpdb->posts SET to_ping = TRIM(REPLACE(to_ping, '$tb_url', '')) WHERE ID = '$ID'");
    8671213}
    8681214
    869 
     1215/**
     1216 * weblog_ping() - {@internal Missing Short Description}}
     1217 *
     1218 * {@internal Missing Long Description}}
     1219 *
     1220 * @since 1.2.0
     1221 * @uses $wp_version
     1222 * @uses IXR_Client
     1223 *
     1224 * @param unknown_type $server
     1225 * @param unknown_type $path
     1226 */
    8701227function weblog_ping($server = '', $path = '') {
    8711228        global $wp_version;
    8721229        include_once(ABSPATH . WPINC . '/class-IXR.php');
    … …  
    8871244// Cache
    8881245//
    8891246
     1247/**
     1248 * clean_comment_cache() - Removes comment ID from the comment cache
     1249 *
     1250 * @since 2.3.0
     1251 * @package WordPress
     1252 * @subpackage Cache
     1253 *
     1254 * @param int $id Comment ID to remove from cache
     1255 */
    8901256function clean_comment_cache($id) {
    8911257        wp_cache_delete($id, 'comment');
    8921258}
    8931259
     1260/**
     1261 * update_comment_cache() - Updates the comment cache of given comments
     1262 *
     1263 * Will add the comments in $comments to the cache. If comment ID already
     1264 * exists in the comment cache then it will not be updated.
     1265 *
     1266 * The comment is added to the cache using the comment group with the key
     1267 * using the ID of the comments.
     1268 *
     1269 * @since 2.3.0
     1270 *
     1271 * @param array $comments Array of comment row objects
     1272 */
    8941273function update_comment_cache($comments) {
    895         foreach ( $comments as $comment )
     1274        foreach ( $comments as $comment ) /** @todo Add "(array)" type cast before $comments to prevent warning */
    8961275                wp_cache_add($comment->comment_ID, $comment, 'comment');
    8971276}
    8981277