Ticket #5578: 5578.r8947.diff

File 5578.r8947.diff, 17.3 KB (added by jacobsantos, 4 years ago)

Complete comment.php inline documentation based off of r8947

  • comment.php

     
    1010 * Checks whether a comment passes internal checks to be allowed to add. 
    1111 * 
    1212 * If comment moderation is set in the administration, then all comments, 
    13  * regardless of their type and whitelist will be set to false. 
     13 * regardless of their type and whitelist will be set to false. If the number of 
     14 * links exceeds the amount in the administration, then the check fails. If any 
     15 * of the parameter contents match the blacklist of words, then the check fails. 
    1416 * 
    15  * If the number of links exceeds the amount in the administration, then the 
    16  * check fails. 
    17  * 
    18  * If any of the parameter contents match the blacklist of words, then the check 
    19  * fails. 
    20  * 
    2117 * If the comment is a trackback and part of the blogroll, then the trackback is 
    2218 * automatically whitelisted. If the comment author was approved before, then 
    2319 * the comment is automatically whitelisted. 
    … …  
    2521 * If none of the checks fail, then the failback is to set the check to pass 
    2622 * (return true). 
    2723 * 
    28  * @since 1.2 
     24 * @since 1.2.0 
    2925 * @uses $wpdb 
    3026 * 
    3127 * @param string $author Comment Author's name 
    … …  
    10298/** 
    10399 * Retrieve the approved comments for post $post_id. 
    104100 * 
    105  * @since 2.0 
     101 * @since 2.0.0 
    106102 * @uses $wpdb 
    107103 * 
    108104 * @param int $post_id The ID of the post 
    … …  
    117113 * Retrieves comment data given a comment ID or comment object. 
    118114 * 
    119115 * If an object is passed then the comment data will be cached and then returned 
    120  * after being passed through a filter. 
     116 * after being passed through a filter. If the comment is empty, then the global 
     117 * comment variable will be used, if it is set. 
    121118 * 
    122  * If the comment is empty, then the global comment variable will be used, if it 
    123  * is set. 
    124  * 
    125  * @since 2.0 
     119 * @since 2.0.0 
    126120 * @uses $wpdb 
    127121 * 
    128122 * @param object|string|int $comment Comment to retrieve. 
    129  * @param string $output Optional. OBJECT or ARRAY_A or ARRAY_N constants 
     123 * @param string $output Optional. OBJECT or ARRAY_A or ARRAY_N constants. 
    130124 * @return object|array|null Depends on $output value. 
    131125 */ 
    132126function &get_comment(&$comment, $output = OBJECT) { 
    … …  
    163157} 
    164158 
    165159/** 
    166  * Retrieve a list of comments 
     160 * Retrieve a list of comments. 
    167161 * 
    168  * {@internal Missing Long Description}} 
     162 * The list of comment arguments are 'status', 'orderby', 'comment_date_gmt', 
     163 * 'order', 'number', 'offset', and 'post_id'. 
    169164 * 
    170  * @package WordPress 
    171  * @subpackage Comment 
    172  * @since 2.7 
     165 * @since 2.7.0 
    173166 * @uses $wpdb 
    174167 * 
    175  * @param mixed $args Optional. Array or string of options 
    176  * @return array List of comments matching defaults or $args 
     168 * @param mixed $args Optional. Array or string of options to override defaults. 
     169 * @return array List of comments. 
    177170 */ 
    178171function get_comments( $args = '' ) { 
    179172        global $wpdb; 
    … …  
    223216/** 
    224217 * Retrieve all of the WordPress supported comment statuses. 
    225218 * 
    226  * Comments have a limited set of valid status values, this provides the 
    227  * comment status values and descriptions. 
     219 * Comments have a limited set of valid status values, this provides the comment 
     220 * status values and descriptions. 
    228221 * 
    229222 * @package WordPress 
    230223 * @subpackage Post 
    231  * @since 2.7 
     224 * @since 2.7.0 
    232225 * 
    233226 * @return array List of comment statuses. 
    234227 */ 
    … …  
    246239/** 
    247240 * The date the last comment was modified. 
    248241 * 
    249  * {@internal Missing Long Description}} 
    250  * 
    251242 * @since 1.5.0 
    252243 * @uses $wpdb 
    253244 * @global array $cache_lastcommentmodified 
    254245 * 
    255246 * @param string $timezone Which timezone to use in reference to 'gmt', 'blog', 
    256  *              or 'server' locations 
    257  * @return string Last comment modified date 
     247 *              or 'server' locations. 
     248 * @return string Last comment modified date. 
    258249 */ 
    259250function get_lastcommentmodified($timezone = 'server') { 
    260251        global $cache_lastcommentmodified, $wpdb; 
    … …  
    284275/** 
    285276 * The amount of comments in a post or total comments. 
    286277 * 
    287  * {@internal Missing Long Description}} 
     278 * A lot like {@link wp_count_comments()}, in that they both return comment 
     279 * stats (albeit with different types). The {@link wp_count_comments()} actual 
     280 * caches, but this function does not. 
    288281 * 
    289282 * @since 2.0.0 
    290283 * @uses $wpdb 
    291284 * 
    292  * @param int $post_id Optional. Comment amount in post if > 0, else total comments blog wide 
    293  * @return array The amount of spam, approved, awaiting moderation, and total 
     285 * @param int $post_id Optional. Comment amount in post if > 0, else total comments blog wide. 
     286 * @return array The amount of spam, approved, awaiting moderation, and total comments. 
    294287 */ 
    295288function get_comment_count( $post_id = 0 ) { 
    296289        global $wpdb; 
    … …  
    371364/** 
    372365 * Validates whether this comment is allowed to be made or not. 
    373366 * 
    374  * {@internal Missing Long Description}} 
    375  * 
    376367 * @since 2.0.0 
    377368 * @uses $wpdb 
    378369 * @uses apply_filters() Calls 'pre_comment_approved' hook on the type of comment 
    … …  
    424415} 
    425416 
    426417/** 
    427  * {@internal Missing Short Description}} 
     418 * Check whether comment flooding is occurring. 
    428419 * 
    429  * {@internal Missing Long Description}} 
     420 * Won't run, if current user can manage options, so to not block 
     421 * administrators. 
    430422 * 
    431423 * @since 2.3.0 
    432424 * @uses $wpdb 
    433  * @uses apply_filters() {@internal Missing Description}} 
    434  * @uses do_action() {@internal Missing Description}} 
     425 * @uses apply_filters() Calls 'comment_flood_filter' filter with first 
     426 *              parameter false, last comment timestamp, new comment timestamp. 
     427 * @uses do_action() Calls 'comment_flood_trigger' action with parameters with 
     428 *              last comment timestamp and new comment timestamp. 
    435429 * 
    436  * @param string $ip {@internal Missing Description}} 
    437  * @param string $email {@internal Missing Description}} 
    438  * @param unknown_type $date {@internal Missing Description}} 
     430 * @param string $ip Comment IP. 
     431 * @param string $email Comment author email address. 
     432 * @param string $date MySQL time string. 
    439433 */ 
    440434function check_comment_flood_db( $ip, $email, $date ) { 
    441435        global $wpdb; 
    … …  
    459453/** 
    460454 * Separates an array of comments into an array keyed by comment_type. 
    461455 * 
    462  * @since 2.7 
     456 * @since 2.7.0 
    463457 * 
    464458 * @param array $comments Array of comments 
    465459 * @return array Array of comments keyed by comment_type. 
    … …  
    480474/** 
    481475 * Does comment contain blacklisted characters or words. 
    482476 * 
    483  * {@internal Missing Long Description}} 
    484  * 
    485477 * @since 1.5.0 
    486  * @uses do_action() Calls 'wp_blacklist_check' hook for all parameters 
     478 * @uses do_action() Calls 'wp_blacklist_check' hook for all parameters. 
    487479 * 
    488480 * @param string $author The author of the comment 
    489481 * @param string $email The email of the comment 
    … …  
    536528} 
    537529 
    538530/** 
    539  * {@internal Missing Short Description}} 
     531 * Retrieve total comments for blog or single post. 
    540532 * 
    541  * {@internal Missing Long Description}} 
     533 * The properties of the returned object contain the 'moderated', 'approved', 
     534 * and spam comments for either the entire blog or single post. Those properties 
     535 * contain the amount of comments that match the status. The 'total_comments' 
     536 * property contains the integer of total comments. 
    542537 * 
    543  * @param unknown_type $post_id 
    544  * @return unknown 
     538 * The comment stats are cached and then retrieved, if they already exist in the 
     539 * cache. 
     540 * 
     541 * @since 2.5.0 
     542 * 
     543 * @param int $post_id Optional. Post ID. 
     544 * @return object Comment stats. 
    545545 */ 
    546546function wp_count_comments( $post_id = 0 ) { 
    547547        global $wpdb; 
    … …  
    618618 * @since 1.0.0 
    619619 * 
    620620 * @param int $comment_id Comment ID 
    621  * @return string|bool Status might be 'deleted', 'approved', 'unapproved', 'spam'. False on failure 
     621 * @return string|bool Status might be 'deleted', 'approved', 'unapproved', 'spam'. False on failure. 
    622622 */ 
    623623function wp_get_comment_status($comment_id) { 
    624624        $comment = get_comment($comment_id); 
    … …  
    642642/** 
    643643 * Get current commenter's name, email, and URL. 
    644644 * 
    645  * Expects cookies content to already be sanitized. User of this function 
    646  * might wish to recheck the returned array for validity. 
     645 * Expects cookies content to already be sanitized. User of this function might 
     646 * wish to recheck the returned array for validity. 
    647647 * 
    648648 * @see sanitize_comment_cookies() Use to sanitize cookies 
    649649 * 
    650650 * @since 2.0.4 
    651651 * 
    652  * @return array Comment author, email, url respectively 
     652 * @return array Comment author, email, url respectively. 
    653653 */ 
    654654function wp_get_current_commenter() { 
    655655        // Cookies should already be sanitized. 
    … …  
    672672/** 
    673673 * Inserts a comment to the database. 
    674674 * 
    675  * {@internal Missing Long Description}} 
     675 * The available comment data key names are 'comment_author_IP', 'comment_date', 
     676 * 'comment_date_gmt', 'comment_parent', 'comment_approved', and 'user_id'. 
    676677 * 
    677678 * @since 2.0.0 
    678679 * @uses $wpdb 
    679680 * 
    680  * @param array $commentdata Contains information on the comment 
    681  * @return int The new comment's id 
     681 * @param array $commentdata Contains information on the comment. 
     682 * @return int The new comment's ID. 
    682683 */ 
    683684function wp_insert_comment($commentdata) { 
    684685        global $wpdb; 
    … …  
    711712} 
    712713 
    713714/** 
    714  * Parses and returns comment information. 
     715 * Filters and sanitizes comment data. 
    715716 * 
    716717 * Sets the comment data 'filtered' field to true when finished. This can be 
    717718 * checked as to whether the comment should be filtered and to keep from 
    … …  
    742743} 
    743744 
    744745/** 
    745  * {@internal Missing Short Description}} 
     746 * Whether comment should be blocked because of comment flood. 
    746747 * 
    747  * {@internal Missing Long Description}} 
    748  * 
    749748 * @since 2.1.0 
    750749 * 
    751  * @param unknown_type $block {@internal Missing Description}} 
    752  * @param unknown_type $time_lastcomment {@internal Missing Description}} 
    753  * @param unknown_type $time_newcomment {@internal Missing Description}} 
    754  * @return unknown {@internal Missing Description}} 
     750 * @param bool $block Whether plugin has already blocked comment. 
     751 * @param int $time_lastcomment Timestamp for last comment. 
     752 * @param int $time_newcomment Timestamp for new comment. 
     753 * @return bool Whether comment should be blocked. 
    755754 */ 
    756755function wp_throttle_comment_flood($block, $time_lastcomment, $time_newcomment) { 
    757756        if ( $block ) // a plugin has already blocked... we'll let that decision stand 
    … …  
    762761} 
    763762 
    764763/** 
    765  * Parses and adds a new comment to the database. 
     764 * Adds a new comment to the database. 
    766765 * 
    767  * {@internal Missing Long Description}} 
     766 * Filters new comment to ensure that the fields are sanitized and valid before 
     767 * inserting comment into database. Calls 'comment_post' action with comment ID 
     768 * and whether comment is approved by WordPress. Also has 'preprocess_comment' 
     769 * filter for processing the comment data before the function handles it. 
    768770 * 
    769771 * @since 1.5.0 
    770772 * @uses apply_filters() Calls 'preprocess_comment' hook on $commentdata parameter array before processing 
    771773 * @uses do_action() Calls 'comment_post' hook on $comment_ID returned from adding the comment and if the comment was approved. 
    772  * @uses wp_filter_comment() Used to filter comment before adding comment 
     774 * @uses wp_filter_comment() Used to filter comment before adding comment. 
    773775 * @uses wp_allow_comment() checks to see if comment is approved. 
    774  * @uses wp_insert_comment() Does the actual comment insertion to the database 
     776 * @uses wp_insert_comment() Does the actual comment insertion to the database. 
    775777 * 
    776778 * @param array $commentdata Contains information on the comment 
    777779 * @return int The ID of the comment after adding. 
    … …  
    814816} 
    815817 
    816818/** 
    817  * Sets the status of comment ID. 
     819 * Sets the status of a comment. 
    818820 * 
    819  * {@internal Missing Long Description}} 
     821 * The 'wp_set_comment_status' action is called after the comment is handled and 
     822 * will only be called, if the comment status is either 'hold', 'approve', or 
     823 * 'spam'. If the comment status is not in the list, then false is returned and 
     824 * if the status is 'delete', then the comment is deleted without calling the 
     825 * action. 
    820826 * 
    821827 * @since 1.0.0 
    822828 * 
    823  * @param int $comment_id Comment ID 
    824  * @param string $comment_status New comment status, either 'hold', 'approve', 'spam', or 'delete' 
     829 * @param int $comment_id Comment ID. 
     830 * @param string $comment_status New comment status, either 'hold', 'approve', 'spam', or 'delete'. 
    825831 * @return bool False on failure or deletion and true on success. 
    826832 */ 
    827833function wp_set_comment_status($comment_id, $comment_status) { 
    … …  
    861867} 
    862868 
    863869/** 
    864  * Parses and updates an existing comment in the database. 
     870 * Updates an existing comment in the database. 
    865871 * 
    866  * {@internal Missing Long Description}} 
     872 * Filters the comment and makes sure certain fields are valid before updating. 
    867873 * 
    868874 * @since 2.0.0 
    869875 * @uses $wpdb 
    870876 * 
    871  * @param array $commentarr Contains information on the comment 
     877 * @param array $commentarr Contains information on the comment. 
    872878 * @return int Comment was updated if value is 1, or was not updated if value is 0. 
    873879 */ 
    874880function wp_update_comment($commentarr) { 
    … …  
    934940 * previously deferred updated post comment counts will then be automatically 
    935941 * updated without having to call wp_update_comment_count() after. 
    936942 * 
    937  * @since 2.5 
     943 * @since 2.5.0 
    938944 * @staticvar bool $_defer 
    939945 * 
    940946 * @param bool $defer 
    … …  
    9951001/** 
    9961002 * Updates the comment count for the post. 
    9971003 * 
    998  * @since 2.5 
     1004 * @since 2.5.0 
    9991005 * @uses $wpdb 
    10001006 * @uses do_action() Calls 'wp_update_comment_count' hook on $post_id, $new, and $old 
    10011007 * @uses do_action() Calls 'edit_posts' hook on $post_id and $post 
    … …  
    10331039/** 
    10341040 * Finds a pingback server URI based on the given URL. 
    10351041 * 
    1036  * {@internal Missing Long Description}} 
     1042 * Checks the HTML for the rel="pingback" link and x-pingback headers. It does 
     1043 * a check for the x-pingback headers first and returns that, if available. The 
     1044 * check for the rel="pingback" has more overhead than just the header. 
    10371045 * 
    10381046 * @since 1.5.0 
    10391047 * @uses $wp_version 
    10401048 * 
    1041  * @param string $url URL to ping 
     1049 * @param string $url URL to ping. 
    10421050 * @param int $timeout_bytes Number of bytes to timeout at. Prevents big file downloads, default is 2048. 
    10431051 * @return bool|string False on failure, string containing URI on success. 
    10441052 */ 
    … …  
    11271135} 
    11281136 
    11291137/** 
    1130  * {@internal Missing Short Description}} 
     1138 * Perform all pingbacks, enclosures, trackbacks, and send to pingback services. 
    11311139 * 
    1132  * {@internal Missing Long Description}} 
    1133  * 
    11341140 * @since 2.1.0 
    11351141 * @uses $wpdb 
    11361142 */ 
    … …  
    11601166} 
    11611167 
    11621168/** 
    1163  * {@internal Missing Short Description}} 
     1169 * Perform trackbacks. 
    11641170 * 
    1165  * {@internal Missing Long Description}} 
    1166  * 
    11671171 * @since 1.5.0 
    11681172 * @uses $wpdb 
    11691173 * 
    1170  * @param int $post_id Post ID to do trackbacks on 
     1174 * @param int $post_id Post ID to do trackbacks on. 
    11711175 */ 
    11721176function do_trackbacks($post_id) { 
    11731177        global $wpdb; 
    … …  
    12041208} 
    12051209 
    12061210/** 
    1207  * {@internal Missing Short Description}} 
     1211 * Sends pings to all of the ping site services. 
    12081212 * 
    1209  * {@internal Missing Long Description}} 
    1210  * 
    12111213 * @since 1.2.0 
    12121214 * 
    12131215 * @param int $post_id Post ID. Not actually used. 
    … …  
    12291231/** 
    12301232 * Pings back the links found in a post. 
    12311233 * 
    1232  * {@internal Missing Long Description}} 
    1233  * 
    12341234 * @since 0.71 
    12351235 * @uses $wp_version 
    12361236 * @uses IXR_Client 
    12371237 * 
    1238  * @param string $content {@internal Missing Description}} 
    1239  * @param int $post_ID {@internal Missing Description}} 
     1238 * @param string $content Post content to check for links. 
     1239 * @param int $post_ID Post ID. 
    12401240 */ 
    12411241function pingback($content, $post_ID) { 
    12421242        global $wp_version; 
    … …  
    13041304} 
    13051305 
    13061306/** 
    1307  * {@internal Missing Short Description}} 
     1307 * Check whether blog is public before returning sites. 
    13081308 * 
    1309  * {@internal Missing Long Description}} 
    1310  * 
    13111309 * @since 2.1.0 
    13121310 * 
    1313  * @param unknown_type $sites {@internal Missing Description}} 
    1314  * @return unknown {@internal Missing Description}} 
     1311 * @param mixed $sites Will return if blog is public, will not return if not public. 
     1312 * @return mixed Empty string if blog is not public, returns $sites, if site is public. 
    13151313 */ 
    13161314function privacy_ping_filter($sites) { 
    13171315        if ( '0' != get_option('blog_public') ) 
    … …  
    13301328 * @uses $wp_version WordPress version 
    13311329 * 
    13321330 * @param string $trackback_url URL to send trackbacks. 
    1333  * @param string $title Title of post 
    1334  * @param string $excerpt Excerpt of post 
    1335  * @param int $ID Post ID 
    1336  * @return mixed Database query from update 
     1331 * @param string $title Title of post. 
     1332 * @param string $excerpt Excerpt of post. 
     1333 * @param int $ID Post ID. 
     1334 * @return mixed Database query from update. 
    13371335 */ 
    13381336function trackback($trackback_url, $title, $excerpt, $ID) { 
    13391337        global $wpdb, $wp_version; 
    … …  
    14121410/** 
    14131411 * Updates the comment cache of given comments. 
    14141412 * 
    1415  * Will add the comments in $comments to the cache. If comment ID already 
    1416  * exists in the comment cache then it will not be updated. 
     1413 * Will add the comments in $comments to the cache. If comment ID already exists 
     1414 * in the comment cache then it will not be updated. The comment is added to the 
     1415 * cache using the comment group with the key using the ID of the comments. 
    14171416 * 
    1418  * The comment is added to the cache using the comment group with the key 
    1419  * using the ID of the comments. 
    1420  * 
    14211417 * @since 2.3.0 
     1418 * @package WordPress 
     1419 * @subpackage Cache 
    14221420 * 
    14231421 * @param array $comments Array of comment row objects 
    14241422 */ 
    … …  
    14341432/** 
    14351433 * Close comments on old posts on the fly, without any extra DB queries. 
    14361434 * 
    1437  * @since 2.7 
    1438  * @package WordPress 
    1439  * @subpackage Internal 
     1435 * @access private 
     1436 * @since 2.7.0 
     1437 * 
     1438 * @param object $posts Post data object. 
     1439 * @return object 
    14401440 */ 
    14411441function _close_comments_for_old_posts( $posts ) { 
    14421442        if ( !is_single() || !get_option('close_comments_for_old_posts') )