WordPress.org
Get WordPress

Make WordPress Core

Changeset 6553


Ignore:
Timestamp:
01/04/2008 08:03:42 PM (17 years ago)
Author:
ryan
Message:

phpdoc for comment.php from darkdragon. fixes #5578

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/comment.php

    r6551 r6553  
    11<?php
    2 
     2/**
     3 * Manages WordPress comments
     4 *
     5 * @package WordPress
     6 */
     7
     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;
    … …  
    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;
    … …  
    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;
    … …  
    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, $wpdb;
    … …  
    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;
    … …  
    152221}
    153222
    154 
     223/**
     224 * get_comment_count() - The amount of comments in a post or total comments
     225 *
     226 * {@internal Missing Long Description}}
     227 *
     228 * @since 2.0.0
     229 * @uses $wpdb
     230 *
     231 * @param int $post_id Optional. Comment amount in post if > 0, else total com
     232ments blog wide
     233 * @return array The amount of spam, approved, awaiting moderation, and total
     234 */
    155235function get_comment_count( $post_id = 0 ) {
    156     global $wpdb;
    157 
    158     $post_id = (int) $post_id;
    159 
    160     $where = '';
    161     if ( $post_id > 0 ) {
    162         $where = "WHERE comment_post_ID = {$post_id}";
    163     }
    164 
    165     $totals = (array) $wpdb->get_results("
    166         SELECT comment_approved, COUNT( * ) AS total
    167         FROM {$wpdb->comments}
    168         {$where}
    169         GROUP BY comment_approved
    170     ", ARRAY_A);
    171 
    172     $comment_count = array(                         
    173         "approved"              => 0,               
    174         "awaiting_moderation"   => 0,
    175         "spam"                  => 0,
    176         "total_comments"        => 0
    177     );
    178 
    179     foreach ( $totals as $row ) {
    180         switch ( $row['comment_approved'] ) {
    181             case 'spam':
    182                 $comment_count['spam'] = $row['total'];
    183                 $comment_count["total_comments"] += $row['total'];
    184                 break;
    185             case 1:
    186                 $comment_count['approved'] = $row['total'];
    187                 $comment_count['total_comments'] += $row['total'];
    188                 break;
    189             case 0:
    190                 $comment_count['awaiting_moderation'] = $row['total'];
    191                 $comment_count['total_comments'] += $row['total'];
    192                 break;
    193             default:
    194                 break;
    195         }
    196     }
    197 
    198     return $comment_count;
    199 }
    200 
    201 
     236    global $wpdb;
     237
     238    $post_id = (int) $post_id;
     239
     240    $where = '';
     241    if ( $post_id > 0 ) {
     242        $where = "WHERE comment_post_ID = {$post_id}";
     243    }
     244
     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);
     251
     252    $comment_count = array(                         
     253        "approved"              => 0,               
     254        "awaiting_moderation"   => 0,
     255        "spam"                  => 0,
     256        "total_comments"        => 0
     257    );
     258
     259    foreach ( $totals as $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    }
     277
     278    return $comment_count;
     279}
     280
     281/**
     282 * sanitize_comment_cookies() - {@internal Missing Short Description}}
     283 *
     284 * {@internal Missing Long Description}}
     285 *
     286 * @since 2.0.4
     287 *
     288 */
    202289function sanitize_comment_cookies() {
    203290    if ( isset($_COOKIE['comment_author_'.COOKIEHASH]) ) {
    … …  
    222309}
    223310
    224 
     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 */
    225324function wp_allow_comment($commentdata) {
    226325    global $wpdb;
    … …  
    261360}
    262361
     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 */
    263376function check_comment_flood_db( $ip, $email, $date ) {
    264377    global $wpdb;
    … …  
    274387}
    275388
     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 */
    276405function wp_blacklist_check($author, $email, $url, $comment, $user_ip, $user_agent) {
    277406    do_action('wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent);
    … …  
    316445}
    317446
    318 
     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 */
    319461function wp_delete_comment($comment_id) {
    320462    global $wpdb;
    … …  
    336478}
    337479
    338 
     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 */
    339488function wp_get_comment_status($comment_id) {
    340489    $comment = get_comment($comment_id);
    … …  
    356505}
    357506
    358 
     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 */
    359519function wp_get_current_commenter() {
    360520    // Cookies should already be sanitized.
    … …  
    375535}
    376536
    377 
     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 */
    378548function wp_insert_comment($commentdata) {
    379549    global $wpdb;
    … …  
    407577}
    408578
    409 
     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 */
    410598function wp_filter_comment($commentdata) {
    411599    $commentdata['user_id']              = apply_filters('pre_user_id', $commentdata['user_ID']);
    … …  
    420608}
    421609
    422 
     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 */
    423622function wp_throttle_comment_flood($block, $time_lastcomment, $time_newcomment) {
    424623    if ( $block ) // a plugin has already blocked... we'll let that decision stand
    … …  
    429628}
    430629
    431 
     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 */
    432645function wp_new_comment( $commentdata ) {
    433646    $commentdata = apply_filters('preprocess_comment', $commentdata);
    … …  
    463676}
    464677
    465 
     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 */
    466689function wp_set_comment_status($comment_id, $comment_status) {
    467690    global $wpdb;
    … …  
    496719}
    497720
    498 
     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 */
    499732function wp_update_comment($commentarr) {
    500733    global $wpdb;
    … …  
    538771}
    539772
    540 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) {
    541788    static $_defer = false;
    542789   
    … …  
    545792        // flush any deferred counts
    546793        if ( !$defer )
    547             wp_update_comment_count( NULL, true );
     794            wp_update_comment_count( null, true );
    548795    }
    549796   
    … …  
    551798}
    552799
     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 */
    553818function wp_update_comment_count($post_id, $do_deferred=false) {
    554819    static $_deferred = array();
    … …  
    558823        foreach ( $_deferred as $i => $_post_id ) {
    559824            wp_update_comment_count_now($_post_id);
    560             unset( $_deferred[$i] );
     825            unset( $_deferred[$i] ); /** @todo Move this outside of the foreach and reset $_deferred to an array instead */
    561826        }
    562827    }
    … …  
    572837}
    573838
     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 */
    574850function wp_update_comment_count_now($post_id) {
    575851    global $wpdb;
    … …  
    595871}
    596872
    597 
    598873//
    599874// Ping and trackback functions.
    600875//
    601876
     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 */
    602889function discover_pingback_server_uri($url, $timeout_bytes = 2048) {
    603890    global $wp_version;
    … …  
    680967}
    681968
    682 
     969/**
     970 * do_all_pings() - {@internal Missing Short Description}}
     971 *
     972 * {@internal Missing Long Description}}
     973 *
     974 * @since 2.1.0
     975 * @uses $wpdb
     976 */
    683977function do_all_pings() {
    684978    global $wpdb;
    … …  
    7071001}
    7081002
     1003/**
     1004 * do_trackbacks() - {@internal Missing Short Description}}
     1005 *
     1006 * {@internal Missing Long Description}}
     1007 *
     1008 * @since 1.5.0
     1009 * @uses $wpdb
     1010 *
     1011 * @param int $post_id Post ID to do trackbacks on
     1012 */
    7091013function do_trackbacks($post_id) {
    7101014    global $wpdb;
    … …  
    7451049}
    7461050
    747 
     1051/**
     1052 * generic_ping() - {@internal Missing Short Description}}
     1053 *
     1054 * {@internal Missing Long Description}}
     1055 *
     1056 * @since 1.2.0
     1057 *
     1058 * @param int $post_id Post ID. Not actually used.
     1059 * @return int Same as Post ID from parameter
     1060 */
    7481061function generic_ping($post_id = 0) {
    7491062    $services = get_option('ping_sites');
    … …  
    7591072}
    7601073
    761 
     1074/**
     1075 * pingback() - Pings back the links found in a post
     1076 *
     1077 * {@internal Missing Long Description}}
     1078 *
     1079 * @since 0.71
     1080 * @uses $wp_version
     1081 * @uses IXR_Client
     1082 *
     1083 * @param string $content {@internal Missing Description}}
     1084 * @param int $post_ID {@internal Missing Description}}
     1085 */
    7621086function pingback($content, $post_ID) {
    7631087    global $wp_version;
    … …  
    8251149}
    8261150
    827 
     1151/**
     1152 * privacy_ping_filter() - {@internal Missing Short Description}}
     1153 *
     1154 * {@internal Missing Long Description}}
     1155 *
     1156 * @since 2.1.0
     1157 *
     1158 * @param unknown_type $sites {@internal Missing Description}}
     1159 * @return unknown {@internal Missing Description}}
     1160 */
    8281161function privacy_ping_filter($sites) {
    8291162    if ( '0' != get_option('blog_public') )
    … …  
    8331166}
    8341167
    835 // Send a Trackback
     1168/**
     1169 * trackback() - Send a Trackback
     1170 *
     1171 * {@internal Missing Long Description}}
     1172 *
     1173 * @since 0.71
     1174 * @uses $wpdb
     1175 * @uses $wp_version WordPress version
     1176 *
     1177 * @param string $trackback_url {@internal Missing Description}}
     1178 * @param string $title {@internal Missing Description}}
     1179 * @param string $excerpt {@internal Missing Description}}
     1180 * @param int $ID {@internal Missing Description}}
     1181 * @return unknown {@internal Missing Description}}
     1182 */
    8361183function trackback($trackback_url, $title, $excerpt, $ID) {
    8371184    global $wpdb, $wp_version;
    … …  
    8651212}
    8661213
    867 
     1214/**
     1215 * weblog_ping() - {@internal Missing Short Description}}
     1216 *
     1217 * {@internal Missing Long Description}}
     1218 *
     1219 * @since 1.2.0
     1220 * @uses $wp_version
     1221 * @uses IXR_Client
     1222 *
     1223 * @param unknown_type $server
     1224 * @param unknown_type $path
     1225 */
    8681226function weblog_ping($server = '', $path = '') {
    8691227    global $wp_version;
    … …  
    8861244//
    8871245
     1246/**
     1247 * clean_comment_cache() - Removes comment ID from the comment cache
     1248 *
     1249 * @since 2.3.0
     1250 * @package WordPress
     1251 * @subpackage Cache
     1252 *
     1253 * @param int $id Comment ID to remove from cache
     1254 */
    8881255function clean_comment_cache($id) {
    8891256    wp_cache_delete($id, 'comment');
    8901257}
    8911258
     1259/**
     1260 * update_comment_cache() - Updates the comment cache of given comments
     1261 *
     1262 * Will add the comments in $comments to the cache. If comment ID already
     1263 * exists in the comment cache then it will not be updated.
     1264 *
     1265 * The comment is added to the cache using the comment group with the key
     1266 * using the ID of the comments.
     1267 *
     1268 * @since 2.3.0
     1269 *
     1270 * @param array $comments Array of comment row objects
     1271 */
    8921272function update_comment_cache($comments) {
    893     foreach ( $comments as $comment )
     1273    foreach ( (array) $comments as $comment )
    8941274        wp_cache_add($comment->comment_ID, $comment, 'comment');
    8951275}
Note: See TracChangeset for help on using the changeset viewer.