Show
Ignore:
Timestamp:
06/15/08 09:34:00 (5 months ago)
Author:
westi
Message:

PHPDoc updates for comment.php. See #5578 props jacobsantos.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/wp-includes/comment.php

    r8052 r8091  
    77 
    88/** 
    9  * check_comment() - Checks whether a comment passes internal checks to be allowed to add 
    10  * 
    11  * {@internal Missing Long Description}} 
     9 * Checks whether a comment passes internal checks to be allowed to add. 
     10 * 
     11 * If comment moderation is set in the administration, then all comments, 
     12 * regardless of their type and whitelist will be set to false. 
     13 * 
     14 * If the number of links exceeds the amount in the administration, then the 
     15 * check fails. 
     16 * 
     17 * If any of the parameter contents match the blacklist of words, then the check 
     18 * fails. 
     19 * 
     20 * If the comment is a trackback and part of the blogroll, then the trackback is 
     21 * automatically whitelisted. If the comment author was approved before, then 
     22 * the comment is automatically whitelisted. 
     23 * 
     24 * If none of the checks fail, then the failback is to set the check to pass 
     25 * (return true). 
    1226 * 
    1327 * @since 1.2 
    1428 * @uses $wpdb 
    1529 * 
    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 }} 
     30 * @param string $author Comment Author's name 
     31 * @param string $email Comment Author's email 
     32 * @param string $url Comment Author's URL 
     33 * @param string $comment Comment contents 
     34 * @param string $user_ip Comment Author's IP address 
     35 * @param string $user_agent Comment Author's User Agent 
     36 * @param string $comment_type Comment type, either user submitted comment, 
     37 *      trackback, or pingback 
     38 * @return bool Whether the checks passed (true) and the comments should be 
     39 *      displayed or set to moderated 
    2440 */ 
    2541function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $comment_type) { 
    …… 
    84100 
    85101/** 
    86  * get_approved_comments() - Returns the approved comments for post $post_id 
     102 * Retrieve the approved comments for post $post_id. 
    87103 * 
    88104 * @since 2.0 
    …… 
    98114 
    99115/** 
    100  * get_comment() - Retrieves comment data given a comment ID or comment object. 
    101  * 
    102  * {@internal Missing Long Description}} 
     116 * Retrieves comment data given a comment ID or comment object. 
     117 * 
     118 * If an object is passed then the comment data will be cached and then returned 
     119 * after being passed through a filter. 
     120 * 
     121 * If the comment is empty, then the global comment variable will be used, if it 
     122 * is set. 
    103123 * 
    104124 * @since 2.0 
    105125 * @uses $wpdb 
    106126 * 
    107  * @param object|string|int $comment {@internal Missing Description}} 
    108  * @param string $output OBJECT or ARRAY_A or ARRAY_N constants 
     127 * @param object|string|int $comment Comment to retrieve. 
     128 * @param string $output Optional. OBJECT or ARRAY_A or ARRAY_N constants 
    109129 * @return object|array|null Depends on $output value. 
    110130 */ 
    …… 
    143163 
    144164/** 
    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(). 
     165 * Retrieve an array of comment data about comment $comment_ID. 
     166 * 
     167 * get_comment() technically does the same thing as this function. This function 
     168 * also appears to reference variables and then not use them or not update them 
     169 * when needed. It is advised to switch to get_comment(), since this function 
     170 * might be deprecated in favor of using get_comment(). 
    151171 * 
    152172 * @deprecated Use get_comment() 
    …… 
    163183 * @return array The comment data 
    164184 */ 
    165 function get_commentdata( $comment_ID, $no_cache = 0, $include_unapproved = false ) { // less flexible, but saves DB queries 
     185function get_commentdata( $comment_ID, $no_cache = 0, $include_unapproved = false ) { 
    166186    global $postc, $wpdb; 
    167187    if ( $no_cache ) { 
    …… 
    187207 
    188208/** 
    189  * get_lastcommentmodified() - The date the last comment was modified 
     209 * The date the last comment was modified. 
    190210 * 
    191211 * {@internal Missing Long Description}} 
    …… 
    195215 * @global array $cache_lastcommentmodified 
    196216 * 
    197  * @param string $timezone Which timezone to use in reference to 'gmt', 'blog', or 'server' locations 
     217 * @param string $timezone Which timezone to use in reference to 'gmt', 'blog', 
     218 *      or 'server' locations 
    198219 * @return string Last comment modified date 
    199220 */ 
    …… 
    224245 
    225246/** 
    226  * get_comment_count() - The amount of comments in a post or total comments 
     247 * The amount of comments in a post or total comments. 
    227248 * 
    228249 * {@internal Missing Long Description}} 
    …… 
    231252 * @uses $wpdb 
    232253 * 
    233  * @param int $post_id Optional. Comment amount in post if > 0, else total com 
    234 ments blog wide 
     254 * @param int $post_id Optional. Comment amount in post if > 0, else total comments blog wide 
    235255 * @return array The amount of spam, approved, awaiting moderation, and total 
    236256 */ 
    …… 
    282302 
    283303/** 
    284  * sanitize_comment_cookies() - {@internal Missing Short Description}} 
    285  * 
    286  * {@internal Missing Long Description}} 
     304 * Sanitizes the cookies sent to the user already. 
     305 * 
     306 * Will only do anything if the cookies have already been created for the user. 
     307 * Mostly used after cookies had been sent to use elsewhere. 
    287308 * 
    288309 * @since 2.0.4 
    289  * 
    290310 */ 
    291311function sanitize_comment_cookies() { 
    …… 
    312332 
    313333/** 
    314  * wp_allow_comment() - Validates whether this comment is allowed to be made or not 
     334 * Validates whether this comment is allowed to be made or not. 
    315335 * 
    316336 * {@internal Missing Long Description}} 
    …… 
    363383 
    364384/** 
    365  * check_comment_flood_db() - {@internal Missing Short Description}} 
     385 * {@internal Missing Short Description}} 
    366386 * 
    367387 * {@internal Missing Long Description}} 
    …… 
    392412 
    393413/** 
    394  * wp_blacklist_check() - Does comment contain blacklisted characters or words 
     414 * Does comment contain blacklisted characters or words. 
    395415 * 
    396416 * {@internal Missing Long Description}} 
    …… 
    449469} 
    450470 
     471/** 
     472 * {@internal Missing Short Description}} 
     473 * 
     474 * {@internal Missing Long Description}} 
     475 * 
     476 * @param unknown_type $post_id 
     477 * @return unknown 
     478 */ 
    451479function wp_count_comments( $post_id = 0 ) { 
    452480    global $wpdb; 
    …… 
    486514 
    487515/** 
    488  * wp_delete_comment() - Removes comment ID and maybe updates post comment count 
    489  * 
    490  * The post comment count will be updated if the comment was approved and has a post 
    491  * ID available. 
     516 * Removes comment ID and maybe updates post comment count. 
     517 * 
     518 * The post comment count will be updated if the comment was approved and has a 
     519 * post ID available. 
    492520 * 
    493521 * @since 2.0.0 
    …… 
    519547 
    520548/** 
    521  * wp_get_comment_status() - The status of a comment by ID 
     549 * The status of a comment by ID. 
    522550 * 
    523551 * @since 1.0.0 
    …… 
    546574 
    547575/** 
    548  * wp_get_current_commenter() - Get current commenter's name, email, and URL 
     576 * Get current commenter's name, email, and URL. 
    549577 * 
    550578 * Expects cookies content to already be sanitized. User of this function 
    …… 
    576604 
    577605/** 
    578  * wp_insert_comment() - Inserts a comment to the database 
     606 * Inserts a comment to the database. 
    579607 * 
    580608 * {@internal Missing Long Description}} 
    …… 
    617645 
    618646/** 
    619  * wp_filter_comment() - Parses and returns comment information 
    620  * 
    621  * Sets the comment data 'filtered' field to true when finished. This 
    622  * can be checked as to whether the comment should be filtered and to 
    623  * keep from filtering the same comment more than once. 
     647 * Parses and returns comment information. 
     648 * 
     649 * Sets the comment data 'filtered' field to true when finished. This can be 
     650 * checked as to whether the comment should be filtered and to keep from 
     651 * filtering the same comment more than once. 
    624652 * 
    625653 * @since 2.0.0 
    …… 
    648676 
    649677/** 
    650  * wp_throttle_comment_flood() - {@internal Missing Short Description}} 
     678 * {@internal Missing Short Description}} 
    651679 * 
    652680 * {@internal Missing Long Description}} 
    …… 
    668696 
    669697/** 
    670  * wp_new_comment() - Parses and adds a new comment to the database 
     698 * Parses and adds a new comment to the database. 
    671699 * 
    672700 * {@internal Missing Long Description}} 
    …… 
    716744 
    717745/** 
    718  * wp_set_comment_status() - Sets the status of comment ID 
     746 * Sets the status of comment ID. 
    719747 * 
    720748 * {@internal Missing Long Description}} 
    …… 
    763791 
    764792/** 
    765  * wp_update_comment() - Parses and updates an existing comment in the database 
     793 * Parses and updates an existing comment in the database. 
    766794 * 
    767795 * {@internal Missing Long Description}} 
    …… 
    822850 
    823851/** 
    824  * wp_defer_comment_counting() - Whether to defer comment counting 
     852 * Whether to defer comment counting. 
    825853 * 
    826854 * When setting $defer to true, all post comment counts will not be updated 
    …… 
    849877 
    850878/** 
    851  * wp_update_comment_count() - Updates the comment count for post(s) 
    852  * 
    853  * When $do_deferred is false (is by default) and the comments have been 
    854  * set to be deferred, the post_id will be added to a queue, which will 
    855  * be updated at a later date and only updated once per post ID. 
    856  * 
    857  * If the comments have not be set up to be deferred, then the post will 
    858  * be updated. When $do_deferred is set to true, then all previous deferred 
    859  * post IDs will be updated along with the current $post_id. 
     879 * Updates the comment count for post(s). 
     880 * 
     881 * When $do_deferred is false (is by default) and the comments have been set to 
     882 * be deferred, the post_id will be added to a queue, which will be updated at a 
     883 * later date and only updated once per post ID. 
     884 * 
     885 * If the comments have not be set up to be deferred, then the post will be 
     886 * updated. When $do_deferred is set to true, then all previous deferred post 
     887 * IDs will be updated along with the current $post_id. 
    860888 * 
    861889 * @since 2.1.0 
    …… 
    888916 
    889917/** 
    890  * wp_update_comment_count_now() - Updates the comment count for the post 
     918 * Updates the comment count for the post. 
    891919 * 
    892920 * @since 2.5 
    …… 
    926954 
    927955/** 
    928  * discover_pingback_server_uri() - Finds a pingback server URI based on the given URL 
     956 * Finds a pingback server URI based on the given URL. 
    929957 * 
    930958 * {@internal Missing Long Description}} 
    …… 
    10221050 
    10231051/** 
    1024  * do_all_pings() - {@internal Missing Short Description}} 
     1052 * {@internal Missing Short Description}} 
    10251053 * 
    10261054 * {@internal Missing Long Description}} 
    …… 
    10551083 
    10561084/** 
    1057  * do_trackbacks() - {@internal Missing Short Description}} 
     1085 * {@internal Missing Short Description}} 
    10581086 * 
    10591087 * {@internal Missing Long Description}} 
    …… 
    10991127 
    11001128/** 
    1101  * generic_ping() - {@internal Missing Short Description}} 
     1129 * {@internal Missing Short Description}} 
    11021130 * 
    11031131 * {@internal Missing Long Description}} 
    …… 
    11221150 
    11231151/** 
    1124  * pingback() - Pings back the links found in a post 
     1152 * Pings back the links found in a post. 
    11251153 * 
    11261154 * {@internal Missing Long Description}} 
    …… 
    11991227 
    12001228/** 
    1201  * privacy_ping_filter() - {@internal Missing Short Description}} 
     1229 * {@internal Missing Short Description}} 
    12021230 * 
    12031231 * {@internal Missing Long Description}} 
    …… 
    12161244 
    12171245/** 
    1218  * trackback() - Send a Trackback 
    1219  * 
    1220  * {@internal Missing Long Description}} 
     1246 * Send a Trackback. 
     1247 * 
     1248 * Updates database when sending trackback to prevent duplicates. 
    12211249 * 
    12221250 * @since 0.71 
    …… 
    12241252 * @uses $wp_version WordPress version 
    12251253 * 
    1226  * @param string $trackback_url {@internal Missing Description}} 
    1227  * @param string $title {@internal Missing Description}} 
    1228  * @param string $excerpt {@internal Missing Description}} 
    1229  * @param int $ID {@internal Missing Description}} 
    1230  * @return unknown {@internal Missing Description}} 
     1254 * @param string $trackback_url URL to send trackbacks. 
     1255 * @param string $title Title of post 
     1256 * @param string $excerpt Excerpt of post 
     1257 * @param int $ID Post ID 
     1258 * @return mixed Database query from update 
    12311259 */ 
    12321260function trackback($trackback_url, $title, $excerpt, $ID) { 
    …… 
    12621290 
    12631291/** 
    1264  * weblog_ping() - {@internal Missing Short Description}} 
    1265  * 
    1266  * {@internal Missing Long Description}} 
     1292 * Send a pingback. 
    12671293 * 
    12681294 * @since 1.2.0 
    …… 
    12701296 * @uses IXR_Client 
    12711297 * 
    1272  * @param unknown_type $server 
    1273  * @param unknown_type $path 
     1298 * @param string $server Host of blog to connect to. 
     1299 * @param string $path Path to send the ping. 
    12741300 */ 
    12751301function weblog_ping($server = '', $path = '') { 
    …… 
    12941320 
    12951321/** 
    1296  * clean_comment_cache() - Removes comment ID from the comment cache 
     1322 * Removes comment ID from the comment cache. 
    12971323 * 
    12981324 * @since 2.3.0 
    …… 
    13071333 
    13081334/** 
    1309  * update_comment_cache() - Updates the comment cache of given comments 
     1335 * Updates the comment cache of given comments. 
    13101336 * 
    13111337 * Will add the comments in $comments to the cache. If comment ID already