WordPress.org
Get WordPress

Make WordPress Core

Changeset 8091


Ignore:
Timestamp:
06/15/2008 09:34:00 AM (16 years ago)
Author:
westi
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed

  • 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
Note: See TracChangeset for help on using the changeset viewer.