Make WordPress Core

Ticket #5578: 5578.r8947.diff

File 5578.r8947.diff, 17.3 KB (added by jacobsantos, 15 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') )