WordPress.org
Get WordPress

Make WordPress Core

Changeset 8949


Ignore:
Timestamp:
09/22/2008 03:39:41 AM (16 years ago)
Author:
azaozz
Message:

Complete comment.php inline documentation, props jacobsantos, fixes #5578

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/comment.php

    r8897 r8949  
    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.
    14  *
    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.
     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.
    2016 *
    2117 * If the comment is a trackback and part of the blogroll, then the trackback is
    … …  
    2622 * (return true).
    2723 *
    28  * @since 1.2
     24 * @since 1.2.0
    2925 * @uses $wpdb
    3026 *
    … …  
    10399 * Retrieve the approved comments for post $post_id.
    104100 *
    105  * @since 2.0
     101 * @since 2.0.0
    106102 * @uses $wpdb
    107103 *
    … …  
    118114 *
    119115 * If an object is passed then the comment data will be cached and then returned
    120  * after being passed through a filter.
    121  *
    122  * If the comment is empty, then the global comment variable will be used, if it
    123  * is set.
    124  *
    125  * @since 2.0
     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.
     118 *
     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 */
    … …  
    164158
    165159/**
    166  * Retrieve a list of comments
    167  *
    168  * {@internal Missing Long Description}}
    169  *
    170  * @package WordPress
    171  * @subpackage Comment
    172  * @since 2.7
     160 * Retrieve a list of comments.
     161 *
     162 * The list of comment arguments are 'status', 'orderby', 'comment_date_gmt',
     163 * 'order', 'number', 'offset', and 'post_id'.
     164 *
     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 = '' ) {
    … …  
    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.
    … …  
    247240 * The date the last comment was modified.
    248241 *
    249  * {@internal Missing Long Description}}
    250  *
    251242 * @since 1.5.0
    252243 * @uses $wpdb
    … …  
    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') {
    … …  
    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 ) {
    … …  
    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
    … …  
    425416
    426417/**
    427  * {@internal Missing Short Description}}
    428  *
    429  * {@internal Missing Long Description}}
     418 * Check whether comment flooding is occurring.
     419 *
     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}}
    435  *
    436  * @param string $ip {@internal Missing Description}}
    437  * @param string $email {@internal Missing Description}}
    438  * @param unknown_type $date {@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.
     429 *
     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 ) {
    … …  
    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
    … …  
    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
    … …  
    537529
    538530/**
    539  * {@internal Missing Short Description}}
    540  *
    541  * {@internal Missing Long Description}}
    542  *
    543  * @param unknown_type $post_id
    544  * @return unknown
     531 * Retrieve total comments for blog or single post.
     532 *
     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.
     537 *
     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 ) {
    … …  
    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) {
    … …  
    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
    … …  
    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() {
    … …  
    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) {
    … …  
    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
    … …  
    743744
    744745/**
    745  * {@internal Missing Short Description}}
    746  *
    747  * {@internal Missing Long Description}}
     746 * Whether comment should be blocked because of comment flood.
    748747 *
    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) {
    … …  
    763762
    764763/**
    765  * Parses and adds a new comment to the database.
    766  *
    767  * {@internal Missing Long Description}}
     764 * Adds a new comment to the database.
     765 *
     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
    … …  
    815817
    816818/**
    817  * Sets the status of comment ID.
    818  *
    819  * {@internal Missing Long Description}}
     819 * Sets the status of a comment.
     820 *
     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 */
    … …  
    862868
    863869/**
    864  * Parses and updates an existing comment in the database.
    865  *
    866  * {@internal Missing Long Description}}
     870 * Updates an existing comment in the database.
     871 *
     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 */
    … …  
    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 *
    … …  
    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
    … …  
    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.
    … …  
    11281136
    11291137/**
    1130  * {@internal Missing Short Description}}
    1131  *
    1132  * {@internal Missing Long Description}}
     1138 * Perform all pingbacks, enclosures, trackbacks, and send to pingback services.
    11331139 *
    11341140 * @since 2.1.0
    … …  
    11611167
    11621168/**
    1163  * {@internal Missing Short Description}}
    1164  *
    1165  * {@internal Missing Long Description}}
     1169 * Perform trackbacks.
    11661170 *
    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) {
    … …  
    12051209
    12061210/**
    1207  * {@internal Missing Short Description}}
    1208  *
    1209  * {@internal Missing Long Description}}
     1211 * Sends pings to all of the ping site services.
    12101212 *
    12111213 * @since 1.2.0
    … …  
    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) {
    … …  
    13051305
    13061306/**
    1307  * {@internal Missing Short Description}}
    1308  *
    1309  * {@internal Missing Long Description}}
     1307 * Check whether blog is public before returning sites.
    13101308 *
    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) {
    … …  
    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) {
    … …  
    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.
    1417  *
    1418  * The comment is added to the cache using the comment group with the key
    1419  * using the ID of the comments.
     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.
    14201416 *
    14211417 * @since 2.3.0
     1418 * @package WordPress
     1419 * @subpackage Cache
    14221420 *
    14231421 * @param array $comments Array of comment row objects
    … …  
    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 ) {
Note: See TracChangeset for help on using the changeset viewer.