WordPress.org

Make WordPress Core

Ticket #25522: 25522.2.diff

File 25522.2.diff, 22.7 KB (added by danieldudzic, 8 years ago)

  • src/wp-includes/comment.php

     
    2727 * @since 1.2.0
    2828 * @uses $wpdb
    2929 *
    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
     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.
    3636 * @param string $comment_type Comment type, either user submitted comment,
    37  *              trackback, or pingback
     37 *              trackback, or pingback.
    3838 * @return bool Whether the checks passed (true) and the comments should be
    39  *              displayed or set to moderated
     39 *              displayed or set to moderated.
    4040 */
    4141function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $comment_type) {
    4242        global $wpdb;
    … …  
    4444        if ( 1 == get_option('comment_moderation') )
    4545                return false; // If moderation is set to manual
    4646
     47        /**
     48         * Filter the comment text.
     49         *
     50         * @since 1.2.1
     51         *
     52         * @param string $comment The comment text.
     53         */
    4754        $comment = apply_filters( 'comment_text', $comment );
    4855
    4956        // Check # of external links
    5057        if ( $max_links = get_option( 'comment_max_links' ) ) {
    5158                $num_links = preg_match_all( '/<a [^>]*href/i', $comment, $out );
     59
     60                /**
     61                 * Filters the maximum amount of links allowed in a comment
     62                 *
     63                 * @since 3.0.0
     64                 *
     65                 * @param int    $num_links The number of links allowed.
     66                 * @param string $url       Comment Author's URL.
     67                 */
    5268                $num_links = apply_filters( 'comment_max_links_url', $num_links, $url ); // provide for counting of $url as a link
    5369                if ( $num_links >= $max_links )
    5470                        return false;
    … …  
    102118 * @since 2.0.0
    103119 * @uses $wpdb
    104120 *
    105  * @param int $post_id The ID of the post
     121 * @param int $post_id The ID of the post.
    106122 * @return array $comments The approved comments
    107123 */
    108124function get_approved_comments($post_id) {
    … …  
    147163                }
    148164        }
    149165
     166        /**
     167         * Fires after a comment is retrieved.
     168         *
     169         * @since 2.3.0
     170         *
     171         * @param mixed $_comment Comment data.
     172         */
    150173        $_comment = apply_filters('get_comment', $_comment);
    151174
    152175        if ( $output == OBJECT ) {
    … …  
    188211 */
    189212class WP_Comment_Query {
    190213        /**
    191          * Metadata query container
     214         * Metadata query container.
    192215         *
    193216         * @since 3.5.0
    194217         * @access public
    … …  
    197220        var $meta_query = false;
    198221
    199222        /**
    200          * Date query container
     223         * Date query container.
    201224         *
    202225         * @since 3.7.0
    203226         * @access public
    … …  
    206229        var $date_query = false;
    207230
    208231        /**
    209          * Execute the query
     232         * Execute the query.
    210233         *
    211234         * @since 3.1.0
    212235         *
    213          * @param string|array $query_vars
     236         * @param string|array $query_vars.
    214237         * @return int|array
    215238         */
    216239        function query( $query_vars ) {
    … …  
    251274                $this->meta_query = new WP_Meta_Query();
    252275                $this->meta_query->parse_query_vars( $this->query_vars );
    253276
     277                /**
     278                 * Fires before comments are retrieved.
     279                 *
     280                 * @since 3.1.0
     281                 *
     282                 * @param WP_Comment_Query Current instance of WP_Comment_Query.
     283                 */
    254284                do_action_ref_array( 'pre_get_comments', array( &$this ) );
    255285                extract( $this->query_vars, EXTR_SKIP );
    256286
    … …  
    376406                }
    377407
    378408                $pieces = array( 'fields', 'join', 'where', 'orderby', 'order', 'limits', 'groupby' );
     409
     410                /**
     411                 * Filter the comments clauses
     412                 *
     413                 * @since 3.1.0
     414                 *
     415                 * @param array An array containing all the pieces.
     416                 * @param WP_Comment_Query Current instance of WP_Comment_Query.
     417                 */
    379418                $clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) );
    380419                foreach ( $pieces as $piece )
    381420                        $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
    … …  
    389428                        return $wpdb->get_var( $query );
    390429
    391430                $comments = $wpdb->get_results( $query );
     431
     432                /**
     433                 * Filter the comment query results.
     434                 *
     435                 * @since 3.1.0
     436                 *
     437                 * @param array An array containing the comments.
     438                 * @param WP_Comment_Query Current instance of WP_Comment_Query.
     439                 */
    392440                $comments = apply_filters_ref_array( 'the_comments', array( $comments, &$this ) );
    393441
    394442                wp_cache_add( $cache_key, $comments, 'comment' );
    … …  
    397445        }
    398446
    399447        /**
    400          * Used internally to generate an SQL string for searching across multiple columns
     448         * Used internally to generate an SQL string for searching across multiple columns.
    401449         *
    402450         * @access protected
    403451         * @since 3.1.0
    … …  
    568616 * @uses delete_metadata
    569617 * @link http://codex.wordpress.org/Function_Reference/delete_comment_meta
    570618 *
    571  * @param int $comment_id comment ID
     619 * @param int $comment_id comment ID.
    572620 * @param string $meta_key Metadata name.
    573621 * @param mixed $meta_value Optional. Metadata value.
    574622 * @return bool True on success, false on failure.
    … …  
    629677        if ( $user->exists() )
    630678                return;
    631679
     680        /**
     681         * Filter the lifetime of the comment cookie.
     682         *
     683         * @since 2.8.0
     684         *
     685         * @param int $seconds Comment cookie lifetime. Default is 30000000 seconds (ca. 347 days).
     686         */
    632687        $comment_cookie_lifetime = apply_filters('comment_cookie_lifetime', 30000000);
    633688        setcookie('comment_author_' . COOKIEHASH, $comment->comment_author, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN);
    634689        setcookie('comment_author_email_' . COOKIEHASH, $comment->comment_author_email, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN);
    … …  
    636691}
    637692
    638693/**
    639  * Sanitizes the cookies sent to the user already.
     694 * Sanitize the cookies sent to the user already.
    640695 *
    641696 * Will only do anything if the cookies have already been created for the user.
    642697 * Mostly used after cookies had been sent to use elsewhere.
    … …  
    645700 */
    646701function sanitize_comment_cookies() {
    647702        if ( isset($_COOKIE['comment_author_'.COOKIEHASH]) ) {
     703                /**
     704                 * Filter the comment author's name cookie before it is set.
     705                 *
     706                 * @since 2.1.0
     707                 *
     708                 * @param string $author_cookie The comment author name.
     709                 */
    648710                $comment_author = apply_filters('pre_comment_author_name', $_COOKIE['comment_author_'.COOKIEHASH]);
    649711                $comment_author = wp_unslash($comment_author);
    650712                $comment_author = esc_attr($comment_author);
    … …  
    652714        }
    653715
    654716        if ( isset($_COOKIE['comment_author_email_'.COOKIEHASH]) ) {
     717                /**
     718                 * Filter the comment author's email cookie before it is set.
     719                 *
     720                 * @since 2.8.0
     721                 *
     722                 * @param string $author_email_cookie The comment author email.
     723                 */
    655724                $comment_author_email = apply_filters('pre_comment_author_email', $_COOKIE['comment_author_email_'.COOKIEHASH]);
    656725                $comment_author_email = wp_unslash($comment_author_email);
    657726                $comment_author_email = esc_attr($comment_author_email);
    … …  
    659728        }
    660729
    661730        if ( isset($_COOKIE['comment_author_url_'.COOKIEHASH]) ) {
     731                /**
     732                 * Filter the comment author's URL cookie before it is set.
     733                 *
     734                 * @since 2.1.0
     735                 *
     736                 * @param string $author_url_cookie The comment author URL.
     737                 */
    662738                $comment_author_url = apply_filters('pre_comment_author_url', $_COOKIE['comment_author_url_'.COOKIEHASH]);
    663739                $comment_author_url = wp_unslash($comment_author_url);
    664740                $_COOKIE['comment_author_url_'.COOKIEHASH] = $comment_author_url;
    … …  
    674750 * @uses apply_filters() Calls 'comment_duplicate_trigger' hook on commentdata.
    675751 * @uses do_action() Calls 'check_comment_flood' hook on $comment_author_IP, $comment_author_email, and $comment_date_gmt
    676752 *
    677  * @param array $commentdata Contains information on the comment
     753 * @param array $commentdata Contains information on the comment.
    678754 * @return mixed Signifies the approval status (0|1|'spam')
    679755 */
    680756function wp_allow_comment($commentdata) {
    … …  
    688764                $dupe .= $wpdb->prepare( "OR comment_author_email = %s ", wp_unslash( $comment_author_email ) );
    689765        $dupe .= $wpdb->prepare( ") AND comment_content = %s LIMIT 1", wp_unslash( $comment_content ) );
    690766        if ( $wpdb->get_var($dupe) ) {
     767                /**
     768                 * Fires when a duplicate comment is detected.
     769                 *
     770                 * @since 3.0.0
     771                 *
     772                 * @param array $commentdata Comment data.
     773                 */
    691774                do_action( 'comment_duplicate_trigger', $commentdata );
    692775                if ( defined('DOING_AJAX') )
    693776                        die( __('Duplicate comment detected; it looks as though you&#8217;ve already said that!') );
    … …  
    695778                wp_die( __('Duplicate comment detected; it looks as though you&#8217;ve already said that!') );
    696779        }
    697780
     781        /**
     782         * Fires before a comment gets approved.
     783         *
     784         * Allows for checking of comment flooding.
     785         *
     786         * @since 2.3.0
     787         *
     788         * @param string $comment_author_IP    The comment author's IP address
     789         * @param string $comment_author_email The comment author's email
     790         * @param string $comment_date_gmt     The date the comment was posted in GMT
     791         */
    698792        do_action( 'check_comment_flood', $comment_author_IP, $comment_author_email, $comment_date_gmt );
    699793
    700794        if ( ! empty( $user_id ) ) {
    … …  
    705799        if ( isset( $user ) && ( $user_id == $post_author || $user->has_cap( 'moderate_comments' ) ) ) {
    706800                // The author and the admins get respect.
    707801                $approved = 1;
    708          } else {
     802        } else {
    709803                // Everyone else's comments will be checked.
    710804                if ( check_comment($comment_author, $comment_author_email, $comment_author_url, $comment_content, $comment_author_IP, $comment_agent, $comment_type) )
    711805                        $approved = 1;
    … …  
    715809                        $approved = 'spam';
    716810        }
    717811
     812        /**
     813         * Filter the comment's approval status before it is set.
     814         *
     815         * @since 2.1.0
     816         *
     817         * @param int|string $approved The approval status. Default is either 1, 0 or 'spam'.
     818         * @param array $commentdata Comment data.
     819         */
    718820        $approved = apply_filters( 'pre_comment_approved', $approved, $commentdata );
    719821        return $approved;
    720822}
    … …  
    744846        if ( $lasttime = $wpdb->get_var( $wpdb->prepare( "SELECT `comment_date_gmt` FROM `$wpdb->comments` WHERE `comment_date_gmt` >= %s AND ( `comment_author_IP` = %s OR `comment_author_email` = %s ) ORDER BY `comment_date_gmt` DESC LIMIT 1", $hour_ago, $ip, $email ) ) ) {
    745847                $time_lastcomment = mysql2date('U', $lasttime, false);
    746848                $time_newcomment  = mysql2date('U', $date, false);
     849                /**
     850                 * Filter the comment flood variable.
     851                 *
     852                 * @since 2.1.0
     853                 *
     854                 * @param bool $bool               True if comment flooding is happening, false if not. Default is false.
     855                 * @param string $time_lastcomment Time when the last comment was posted.
     856                 * @param string $time_newcomment  Time when the new comment was posted.
     857                 */
    747858                $flood_die = apply_filters('comment_flood_filter', false, $time_lastcomment, $time_newcomment);
    748859                if ( $flood_die ) {
     860                        /**
     861                         * Fires before comment flooding message is triggered
     862                         *
     863                         * @since 2.1.0
     864                         *
     865                         * @param string $time_lastcomment Time when the last comment was posted
     866                         * @param string $time_newcomment  Time when the new comment was posted
     867                         */
    749868                        do_action('comment_flood_trigger', $time_lastcomment, $time_newcomment);
    750869
    751870                        if ( defined('DOING_AJAX') )
    … …  
    8931012 * @since 1.5.0
    8941013 * @uses do_action() Calls 'wp_blacklist_check' hook for all parameters.
    8951014 *
    896  * @param string $author The author of the comment
    897  * @param string $email The email of the comment
    898  * @param string $url The url used in the comment
    899  * @param string $comment The comment content
    900  * @param string $user_ip The comment author IP address
    901  * @param string $user_agent The author's browser user agent
     1015 * @param string $author The author of the comment.
     1016 * @param string $email The email of the comment.
     1017 * @param string $url The url used in the comment.
     1018 * @param string $comment The comment content.
     1019 * @param string $user_ip The comment author IP address.
     1020 * @param string $user_agent The author's browser user agent.
    9021021 * @return bool True if comment contains blacklisted content, false if comment does not
    9031022 */
    9041023function wp_blacklist_check($author, $email, $url, $comment, $user_ip, $user_agent) {
     1024        /**
     1025         * Fires before the comment is tested for blacklisted characters or words.
     1026         *
     1027         * @since 1.5.0
     1028         *
     1029         * @param string $author     The author of the comment
     1030         * @param string $email      The email of the comment
     1031         * @param string $url        The url used in the comment
     1032         * @param string $comment    The comment content
     1033         * @param string $user_ip    The comment author IP address
     1034         * @param string $user_agent The author's browser user agent
     1035         */
    9051036        do_action('wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent);
    9061037
    9071038        $mod_keys = trim( get_option('blacklist_keys') );
    … …  
    9211052
    9221053                $pattern = "#$word#i";
    9231054                if (
    924                            preg_match($pattern, $author)
     1055                                preg_match($pattern, $author)
    9251056                        || preg_match($pattern, $email)
    9261057                        || preg_match($pattern, $url)
    9271058                        || preg_match($pattern, $comment)
    9281059                        || preg_match($pattern, $user_ip)
    9291060                        || preg_match($pattern, $user_agent)
    930                  )
     1061                )
    9311062                        return true;
    9321063        }
    9331064        return false;
    … …  
    9541085
    9551086        $post_id = (int) $post_id;
    9561087
     1088        /**
     1089         * Filter the comments count for the given post.
     1090         *
     1091         * @since
     1092         *
     1093         * @param array $count An empty array.
     1094         * @param int $post_id Post ID.
     1095         */
    9571096        $stats = apply_filters('wp_count_comments', array(), $post_id);
    9581097        if ( !empty($stats) )
    9591098                return $stats;
    … …  
    10071146 * @uses do_action() Calls 'wp_set_comment_status' hook on comment ID with 'delete' set for the second parameter
    10081147 * @uses wp_transition_comment_status() Passes new and old comment status along with $comment object
    10091148 *
    1010  * @param int $comment_id Comment ID
     1149 * @param int $comment_id Comment ID.
    10111150 * @param bool $force_delete Whether to bypass trash and force deletion. Default is false.
    10121151 * @return bool True on success, false on failure.
    10131152 */
    … …  
    10191158        if ( !$force_delete && EMPTY_TRASH_DAYS && !in_array( wp_get_comment_status($comment_id), array( 'trash', 'spam' ) ) )
    10201159                return wp_trash_comment($comment_id);
    10211160
     1161        /**
     1162         * Fires before a comment is deleted.
     1163         *
     1164         * @since 2.1.0
     1165         *
     1166         * @param int $comment_id Comment ID.
     1167         */
    10221168        do_action('delete_comment', $comment_id);
    10231169
    10241170        // Move children up a level.
    … …  
    10351181
    10361182        if ( ! $wpdb->delete( $wpdb->comments, array( 'comment_ID' => $comment_id ) ) )
    10371183                return false;
     1184
     1185        /**
     1186         * Fires after comment metadata has been deleted.
     1187         *
     1188         * @since 2.9.0
     1189         *
     1190         * @param int $comment_id Comment ID.
     1191         */
    10381192        do_action('deleted_comment', $comment_id);
    10391193
    10401194        $post_id = $comment->comment_post_ID;
    … …  
    10431197
    10441198        clean_comment_cache($comment_id);
    10451199
     1200        /**
     1201         * Fires before transitioning the comment's status to 'delete'.
     1202         *
     1203         * @since 2.1.0
     1204         *
     1205         * @param int $comment_id Comment ID.
     1206         * @param string $status The new status 'delete'.
     1207         */
    10461208        do_action('wp_set_comment_status', $comment_id, 'delete');
    10471209        wp_transition_comment_status('delete', $comment->comment_approved, $comment);
    10481210        return true;
    10491211}
    10501212
    10511213/**
    1052  * Moves a comment to the Trash
     1214 * Moves a comment to the Trash.
    10531215 *
    10541216 * If trash is disabled, comment is permanently deleted.
    10551217 *
    … …  
    10681230        if ( !$comment = get_comment($comment_id) )
    10691231                return false;
    10701232
     1233        /**
     1234         * Fires before a comment is sent to the trash.
     1235         *
     1236         * @since 2.9.0
     1237         *
     1238         * @param int $comment_id Comment ID.
     1239         */
    10711240        do_action('trash_comment', $comment_id);
    10721241
    10731242        if ( wp_set_comment_status($comment_id, 'trash') ) {
    10741243                add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved);
    10751244                add_comment_meta($comment_id, '_wp_trash_meta_time', time() );
     1245
     1246                /**
     1247                 * Fires after a comment is sent to the trash.
     1248                 *
     1249                 * @since 2.9.0
     1250                 *
     1251                 * @param int $comment_id Comment ID.
     1252                 */
    10761253                do_action('trashed_comment', $comment_id);
    10771254                return true;
    10781255        }
    … …  
    10811258}
    10821259
    10831260/**
    1084  * Removes a comment from the Trash
     1261 * Removes a comment from the Trash.
    10851262 *
    10861263 * @since 2.9.0
    10871264 * @uses do_action() on 'untrash_comment' before untrashing
    … …  
    10941271        if ( ! (int)$comment_id )
    10951272                return false;
    10961273
     1274        /**
     1275         * Fires before a comment is restored from the trash.
     1276         *
     1277         * @since 2.9.0
     1278         *
     1279         * @param int $comment_id Comment ID.
     1280         */
    10971281        do_action('untrash_comment', $comment_id);
    10981282
    10991283        $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true);
    … …  
    11031287        if ( wp_set_comment_status($comment_id, $status) ) {
    11041288                delete_comment_meta($comment_id, '_wp_trash_meta_time');
    11051289                delete_comment_meta($comment_id, '_wp_trash_meta_status');
     1290                /**
     1291                 * Fires after a comment is restored from the trash.
     1292                 *
     1293                 * @since 2.9.0
     1294                 *
     1295                 * @param int $comment_id Comment ID.
     1296                 */
    11061297                do_action('untrashed_comment', $comment_id);
    11071298                return true;
    11081299        }
    … …  
    11111302}
    11121303
    11131304/**
    1114  * Marks a comment as Spam
     1305 * Marks a comment as Spam.
    11151306 *
    11161307 * @since 2.9.0
    11171308 * @uses do_action() on 'spam_comment' before spamming
    … …  
    11241315        if ( !$comment = get_comment($comment_id) )
    11251316                return false;
    11261317
     1318        /**
     1319         * Fires before a comment is marked as spam.
     1320         *
     1321         * @since 2.9.0
     1322         *
     1323         * @param int $comment_id Comment ID.
     1324         */
    11271325        do_action('spam_comment', $comment_id);
    11281326
    11291327        if ( wp_set_comment_status($comment_id, 'spam') ) {
    11301328                add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved);
     1329                /**
     1330                 * Fires after a comment is marked as spam.
     1331                 *
     1332                 * @since 2.9.0
     1333                 *
     1334                 * @param int $comment_id Comment ID.
     1335                 */
    11311336                do_action('spammed_comment', $comment_id);
    11321337                return true;
    11331338        }
    … …  
    11361341}
    11371342
    11381343/**
    1139  * Removes a comment from the Spam
     1344 * Fires before a comment is un-marked as Spam.
    11401345 *
    11411346 * @since 2.9.0
    11421347 * @uses do_action() on 'unspam_comment' before unspamming
    … …  
    11491354        if ( ! (int)$comment_id )
    11501355                return false;
    11511356
     1357        /**
     1358         * Fires after a comment is un-marked as Spam.
     1359         *
     1360         * @since 2.9.0
     1361         *
     1362         * @param int $comment_id Comment ID.
     1363         */
    11521364        do_action('unspam_comment', $comment_id);
    11531365
    11541366        $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true);
    … …  
    11571369
    11581370        if ( wp_set_comment_status($comment_id, $status) ) {
    11591371                delete_comment_meta($comment_id, '_wp_trash_meta_status');
     1372
     1373                /**
     1374                 * Fires after a comment is removed from the Spam.
     1375                 *
     1376                 * @since 2.9.0
     1377                 *
     1378                 * @param int $comment_id Comment ID.
     1379                 */
    11601380                do_action('unspammed_comment', $comment_id);
    11611381                return true;
    11621382        }
    … …  
    11691389 *
    11701390 * @since 1.0.0
    11711391 *
    1172  * @param int $comment_id Comment ID
     1392 * @param int $comment_id Comment ID.
    11731393 * @return string|bool Status might be 'trash', 'approved', 'unapproved', 'spam'. False on failure.
    11741394 */
    11751395function wp_get_comment_status($comment_id) {
    … …  
    13051525                wp_update_comment_count($comment_post_ID);
    13061526
    13071527        $comment = get_comment($id);
     1528
     1529        /**
     1530         * Fires after the comment is inserted.
     1531         *
     1532         * @since
     1533         *
     1534         * @param int $id Comment ID.
     1535         * @param object $comment Comment object.
     1536         */
    13081537        do_action('wp_insert_comment', $id, $comment);
    13091538
    13101539        wp_cache_set( 'last_changed', microtime(), 'comment' );
    … …  
    13131542}
    13141543
    13151544/**
    1316  * Filters and sanitizes comment data.
     1545 * Filter and sanitize comment data.
    13171546 *
    13181547 * Sets the comment data 'filtered' field to true when finished. This can be
    13191548 * checked as to whether the comment should be filtered and to keep from
    … …  
    13671596/**
    13681597 * Adds a new comment to the database.
    13691598 *
    1370  * Filters new comment to ensure that the fields are sanitized and valid before
     1599 * Filter new comment to ensure that the fields are sanitized and valid before
    13711600 * inserting comment into database. Calls 'comment_post' action with comment ID
    13721601 * and whether comment is approved by WordPress. Also has 'preprocess_comment'
    13731602 * filter for processing the comment data before the function handles it.
    … …  
    14911720/**
    14921721 * Updates an existing comment in the database.
    14931722 *
    1494  * Filters the comment and makes sure certain fields are valid before updating.
     1723 * Filter the comment and makes sure certain fields are valid before updating.
    14951724 *
    14961725 * @since 2.0.0
    14971726 * @uses $wpdb
    … …  
    15841813 * @since 2.1.0
    15851814 * @see wp_update_comment_count_now() For what could cause a false return value
    15861815 *
    1587  * @param int $post_id Post ID
    1588  * @param bool $do_deferred Whether to process previously deferred post comment counts
     1816 * @param int $post_id Post ID.
     1817 * @param bool $do_deferred Whether to process previously deferred post comment counts.
    15891818 * @return bool True on success, false on failure
    15901819 */
    15911820function wp_update_comment_count($post_id, $do_deferred=false) {
    … …  
    16171846 * @uses do_action() Calls 'wp_update_comment_count' hook on $post_id, $new, and $old
    16181847 * @uses do_action() Calls 'edit_posts' hook on $post_id and $post
    16191848 *
    1620  * @param int $post_id Post ID
     1849 * @param int $post_id Post ID.
    16211850 * @return bool True on success, false on '0' $post_id or if post with ID does not exist.
    16221851 */
    16231852function wp_update_comment_count_now($post_id) {
    … …  
    18632092
    18642093                if ( $pingback_server_url ) {
    18652094                        @ set_time_limit( 60 );
    1866                          // Now, the RPC call
     2095                        // Now, the RPC call
    18672096                        $pagelinkedfrom = get_permalink($post_ID);
    18682097
    18692098                        // using a timeout of 3 seconds should be enough to cover slow servers
    … …  
    19602189}
    19612190
    19622191/**
    1963  * Default filter attached to pingback_ping_source_uri to validate the pingback's Source URI
     2192 * Default filter attached to pingback_ping_source_uri to validate the pingback's Source URI.
    19642193 *
    19652194 * @since 3.5.1
    19662195 * @see wp_http_validate_url()
    … …  
    20012230 * @package WordPress
    20022231 * @subpackage Cache
    20032232 *
    2004  * @param int|array $ids Comment ID or array of comment IDs to remove from cache
     2233 * @param int|array $ids Comment ID or array of comment IDs to remove from cache.
    20052234 */
    20062235function clean_comment_cache($ids) {
    20072236        foreach ( (array) $ids as $id )
    … …  
    20212250 * @package WordPress
    20222251 * @subpackage Cache
    20232252 *
    2024  * @param array $comments Array of comment row objects
     2253 * @param array $comments Array of comment row objects.
    20252254 */
    20262255function update_comment_cache($comments) {
    20272256        foreach ( (array) $comments as $comment )
    … …  
    20462275        if ( empty( $posts ) || ! $query->is_singular() || ! get_option( 'close_comments_for_old_posts' ) )
    20472276                return $posts;
    20482277
     2278        /**
     2279         * Filter the post types on which old comments should be closed automatically.
     2280         *
     2281         * @since 3.2.0
     2282         *
     2283         * @param array $post_types An array of registered post types.
     2284         */
    20492285        $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) );
    20502286        if ( ! in_array( $posts[0]->post_type, $post_types ) )
    20512287                return $posts;
    … …  
    20682304 * @access private
    20692305 * @since 2.7.0
    20702306 *
    2071  * @param bool $open Comments open or closed
    2072  * @param int $post_id Post ID
     2307 * @param bool $open Comments open or closed.
     2308 * @param int $post_id Post ID.
    20732309 * @return bool $open
    20742310 */
    20752311function _close_comments_for_old_post( $open, $post_id ) {
    … …  
    20852321
    20862322        $post = get_post($post_id);
    20872323
     2324        /** This filter is documented in wp-includes/comment.php */
    20882325        $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) );
    20892326        if ( ! in_array( $post->post_type, $post_types ) )
    20902327                return $open;