Make WordPress Core

Ticket #25522: 25522.3.diff

File 25522.3.diff, 26.4 KB (added by kpdesign, 12 years ago)

Third pass

  • src/wp-includes/comment.php

     
    4444        if ( 1 == get_option('comment_moderation') )
    4545                return false; // If moderation is set to manual
    4646
     47        /** This filter is documented in wp-includes/comment-template.php */
    4748        $comment = apply_filters( 'comment_text', $comment );
    4849
    4950        // Check # of external links
    5051        if ( $max_links = get_option( 'comment_max_links' ) ) {
    5152                $num_links = preg_match_all( '/<a [^>]*href/i', $comment, $out );
    52                 $num_links = apply_filters( 'comment_max_links_url', $num_links, $url ); // provide for counting of $url as a link
     53                /**
     54                 * Filter the maximum number of links allowed in a comment.
     55                 *
     56                 * @since 3.0.0
     57                 *
     58                 * @param int    $num_links The number of links allowed.
     59                 * @param string $url       Comment author's URL. Included in allowed links total.
     60                 */
     61                $num_links = apply_filters( 'comment_max_links_url', $num_links, $url );
    5362                if ( $num_links >= $max_links )
    5463                        return false;
    5564        }
     
    147156                }
    148157        }
    149158
    150         $_comment = apply_filters('get_comment', $_comment);
     159        /**
     160         * Fires after a comment is retrieved.
     161         *
     162         * @since 2.3.0
     163         *
     164         * @param mixed $_comment Comment data.
     165         */
     166        $_comment = apply_filters( 'get_comment', $_comment );
    151167
    152168        if ( $output == OBJECT ) {
    153169                return $_comment;
     
    251267                $this->meta_query = new WP_Meta_Query();
    252268                $this->meta_query->parse_query_vars( $this->query_vars );
    253269
     270                /**
     271                 * Fires before comments are retrieved.
     272                 *
     273                 * @since 3.1.0
     274                 *
     275                 * @param WP_Comment_Query &$this Current instance of WP_Comment_Query.
     276                 */
    254277                do_action_ref_array( 'pre_get_comments', array( &$this ) );
    255278                extract( $this->query_vars, EXTR_SKIP );
    256279
     
    376399                }
    377400
    378401                $pieces = array( 'fields', 'join', 'where', 'orderby', 'order', 'limits', 'groupby' );
     402                /**
     403                 * Filter the comment query clauses.
     404                 *
     405                 * @since 3.1.0
     406                 *
     407                 * @param array            $pieces An array containing the query pieces, passed by reference.
     408                 * @param WP_Comment_Query &$this  Current instance of WP_Comment_Query.
     409                 */
    379410                $clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) );
    380411                foreach ( $pieces as $piece )
    381412                        $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
     
    389420                        return $wpdb->get_var( $query );
    390421
    391422                $comments = $wpdb->get_results( $query );
     423                /**
     424                 * Filter the comment query results.
     425                 *
     426                 * @since 3.1.0
     427                 *
     428                 * @param array            $comments An array of comment data, passed by reference.
     429                 * @param WP_Comment_Query &$this    Current instance of WP_Comment_Query.
     430                 */
    392431                $comments = apply_filters_ref_array( 'the_comments', array( $comments, &$this ) );
    393432
    394433                wp_cache_add( $cache_key, $comments, 'comment' );
     
    629668        if ( $user->exists() )
    630669                return;
    631670
    632         $comment_cookie_lifetime = apply_filters('comment_cookie_lifetime', 30000000);
     671        /**
     672         * Filter the lifetime of the comment cookie.
     673         *
     674         * @since 2.8.0
     675         *
     676         * @param int $seconds Comment cookie lifetime. Default '30000000'.
     677         */
     678        $comment_cookie_lifetime = apply_filters( 'comment_cookie_lifetime', 30000000 );
    633679        setcookie('comment_author_' . COOKIEHASH, $comment->comment_author, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN);
    634680        setcookie('comment_author_email_' . COOKIEHASH, $comment->comment_author_email, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN);
    635681        setcookie('comment_author_url_' . COOKIEHASH, esc_url($comment->comment_author_url), time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN);
     
    645691 */
    646692function sanitize_comment_cookies() {
    647693        if ( isset($_COOKIE['comment_author_'.COOKIEHASH]) ) {
    648                 $comment_author = apply_filters('pre_comment_author_name', $_COOKIE['comment_author_'.COOKIEHASH]);
     694                /**
     695                 * Filter the comment author's name cookie before it is set.
     696                 *
     697                 * @since 1.5.2
     698                 *
     699                 * @param string $author_cookie The comment author name cookie.
     700                 */
     701                $comment_author = apply_filters( 'pre_comment_author_name', $_COOKIE['comment_author_'.COOKIEHASH] );
    649702                $comment_author = wp_unslash($comment_author);
    650703                $comment_author = esc_attr($comment_author);
    651704                $_COOKIE['comment_author_'.COOKIEHASH] = $comment_author;
     
    652705        }
    653706
    654707        if ( isset($_COOKIE['comment_author_email_'.COOKIEHASH]) ) {
    655                 $comment_author_email = apply_filters('pre_comment_author_email', $_COOKIE['comment_author_email_'.COOKIEHASH]);
     708                /**
     709                 * Filter the comment author's email cookie before it is set.
     710                 *
     711                 * @since 1.5.2
     712                 *
     713                 * @param string $author_email_cookie The comment author email cookie.
     714                 */
     715                $comment_author_email = apply_filters( 'pre_comment_author_email', $_COOKIE['comment_author_email_'.COOKIEHASH] );
    656716                $comment_author_email = wp_unslash($comment_author_email);
    657717                $comment_author_email = esc_attr($comment_author_email);
    658718                $_COOKIE['comment_author_email_'.COOKIEHASH] = $comment_author_email;
     
    659719        }
    660720
    661721        if ( isset($_COOKIE['comment_author_url_'.COOKIEHASH]) ) {
    662                 $comment_author_url = apply_filters('pre_comment_author_url', $_COOKIE['comment_author_url_'.COOKIEHASH]);
     722                /**
     723                 * Filter the comment author's URL cookie before it is set.
     724                 *
     725                 * @since 1.5.2
     726                 *
     727                 * @param string $author_url_cookie The comment author URL cookie.
     728                 */
     729                $comment_author_url = apply_filters( 'pre_comment_author_url', $_COOKIE['comment_author_url_'.COOKIEHASH] );
    663730                $comment_author_url = wp_unslash($comment_author_url);
    664731                $_COOKIE['comment_author_url_'.COOKIEHASH] = $comment_author_url;
    665732        }
     
    688755                $dupe .= $wpdb->prepare( "OR comment_author_email = %s ", wp_unslash( $comment_author_email ) );
    689756        $dupe .= $wpdb->prepare( ") AND comment_content = %s LIMIT 1", wp_unslash( $comment_content ) );
    690757        if ( $wpdb->get_var($dupe) ) {
     758                /**
     759                 * Fires when a duplicate comment is detected.
     760                 *
     761                 * @since 3.0.0
     762                 *
     763                 * @param array $commentdata Comment data.
     764                 */
    691765                do_action( 'comment_duplicate_trigger', $commentdata );
    692766                if ( defined('DOING_AJAX') )
    693767                        die( __('Duplicate comment detected; it looks as though you&#8217;ve already said that!') );
     
    695769                wp_die( __('Duplicate comment detected; it looks as though you&#8217;ve already said that!') );
    696770        }
    697771
     772        /**
     773         * Fires before a comment is approved.
     774         *
     775         * Allows for checking of comment flooding.
     776         *
     777         * @since 2.3.0
     778         *
     779         * @param string $comment_author_IP    The comment author's IP address.
     780         * @param string $comment_author_email The comment author's email.
     781         * @param string $comment_date_gmt     The GMT date the comment was posted.
     782         */
    698783        do_action( 'check_comment_flood', $comment_author_IP, $comment_author_email, $comment_date_gmt );
    699784
    700785        if ( ! empty( $user_id ) ) {
     
    705790        if ( isset( $user ) && ( $user_id == $post_author || $user->has_cap( 'moderate_comments' ) ) ) {
    706791                // The author and the admins get respect.
    707792                $approved = 1;
    708          } else {
     793        } else {
    709794                // Everyone else's comments will be checked.
    710795                if ( check_comment($comment_author, $comment_author_email, $comment_author_url, $comment_content, $comment_author_IP, $comment_agent, $comment_type) )
    711796                        $approved = 1;
     
    715800                        $approved = 'spam';
    716801        }
    717802
     803        /**
     804         * Filter the comment's approval status before it is set.
     805         *
     806         * @since 2.1.0
     807         *
     808         * @param int|string $approved    The approval status. Accepts 1, 0, or 'spam'.
     809         * @param array      $commentdata Comment data.
     810         */
    718811        $approved = apply_filters( 'pre_comment_approved', $approved, $commentdata );
    719812        return $approved;
    720813}
     
    744837        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 ) ) ) {
    745838                $time_lastcomment = mysql2date('U', $lasttime, false);
    746839                $time_newcomment  = mysql2date('U', $date, false);
    747                 $flood_die = apply_filters('comment_flood_filter', false, $time_lastcomment, $time_newcomment);
     840                /**
     841                 * Filter the comment flood variable.
     842                 *
     843                 * @since 2.1.0
     844                 *
     845                 * @param bool   $bool             Whether comment flooding is occurring. Default false.
     846                 * @param string $time_lastcomment Time when the last comment was posted.
     847                 * @param string $time_newcomment  Time when the new comment was posted.
     848                 */
     849                $flood_die = apply_filters( 'comment_flood_filter', false, $time_lastcomment, $time_newcomment );
    748850                if ( $flood_die ) {
    749                         do_action('comment_flood_trigger', $time_lastcomment, $time_newcomment);
     851                        /**
     852                         * Fires before comment flood message is triggered.
     853                         *
     854                         * @since 1.5.2
     855                         *
     856                         * @param string $time_lastcomment Time when the last comment was posted.
     857                         * @param string $time_newcomment  Time when the new comment was posted.
     858                         */
     859                        do_action( 'comment_flood_trigger', $time_lastcomment, $time_newcomment );
    750860
    751861                        if ( defined('DOING_AJAX') )
    752862                                die( __('You are posting comments too quickly. Slow down.') );
     
    9021012 * @return bool True if comment contains blacklisted content, false if comment does not
    9031013 */
    9041014function wp_blacklist_check($author, $email, $url, $comment, $user_ip, $user_agent) {
    905         do_action('wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent);
     1015        /**
     1016         * Fires before the comment is tested for blacklisted characters or words.
     1017         *
     1018         * @since 1.5.2
     1019         *
     1020         * @param string $author     The comment author.
     1021         * @param string $email      The comment author's email.
     1022         * @param string $url        The comment author's URL.
     1023         * @param string $comment    The comment content.
     1024         * @param string $user_ip    The comment author's IP address.
     1025         * @param string $user_agent The comment author's browser user agent.
     1026         */
     1027        do_action( 'wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent );
    9061028
    9071029        $mod_keys = trim( get_option('blacklist_keys') );
    9081030        if ( '' == $mod_keys )
     
    9541076
    9551077        $post_id = (int) $post_id;
    9561078
    957         $stats = apply_filters('wp_count_comments', array(), $post_id);
     1079        /**
     1080         * Filter the comments count for the given post.
     1081         *
     1082         * @since 2.7.0
     1083         *
     1084         * @param array $count   An empty array.
     1085         * @param int   $post_id The post ID.
     1086         */
     1087        $stats = apply_filters( 'wp_count_comments', array(), $post_id );
    9581088        if ( !empty($stats) )
    9591089                return $stats;
    9601090
     
    10191149        if ( !$force_delete && EMPTY_TRASH_DAYS && !in_array( wp_get_comment_status($comment_id), array( 'trash', 'spam' ) ) )
    10201150                return wp_trash_comment($comment_id);
    10211151
    1022         do_action('delete_comment', $comment_id);
     1152        /**
     1153         * Fires before a comment is deleted.
     1154         *
     1155         * @since 1.2.1
     1156         *
     1157         * @param int $comment_id The comment ID.
     1158         */
     1159        do_action( 'delete_comment', $comment_id );
    10231160
    10241161        // Move children up a level.
    10251162        $children = $wpdb->get_col( $wpdb->prepare("SELECT comment_ID FROM $wpdb->comments WHERE comment_parent = %d", $comment_id) );
     
    10351172
    10361173        if ( ! $wpdb->delete( $wpdb->comments, array( 'comment_ID' => $comment_id ) ) )
    10371174                return false;
    1038         do_action('deleted_comment', $comment_id);
    10391175
     1176        /**
     1177         * Fires after the comment metadata has been deleted.
     1178         *
     1179         * @since 2.9.0
     1180         *
     1181         * @param int $comment_id The comment ID.
     1182         */
     1183        do_action( 'deleted_comment', $comment_id );
     1184
    10401185        $post_id = $comment->comment_post_ID;
    10411186        if ( $post_id && $comment->comment_approved == 1 )
    10421187                wp_update_comment_count($post_id);
     
    10431188
    10441189        clean_comment_cache($comment_id);
    10451190
    1046         do_action('wp_set_comment_status', $comment_id, 'delete');
     1191        /**
     1192         * Fires before changing the comment's status to 'delete'.
     1193         *
     1194         * @since 1.5.2
     1195         *
     1196         * @param int    $comment_id The comment ID.
     1197         * @param string $status     The new status 'delete'.
     1198         */
     1199        do_action( 'wp_set_comment_status', $comment_id, 'delete' );
    10471200        wp_transition_comment_status('delete', $comment->comment_approved, $comment);
    10481201        return true;
    10491202}
     
    10681221        if ( !$comment = get_comment($comment_id) )
    10691222                return false;
    10701223
    1071         do_action('trash_comment', $comment_id);
     1224        /**
     1225         * Fires before a comment is sent to Trash.
     1226         *
     1227         * @since 2.9.0
     1228         *
     1229         * @param int $comment_id The comment ID.
     1230         */
     1231        do_action( 'trash_comment', $comment_id );
    10721232
    10731233        if ( wp_set_comment_status($comment_id, 'trash') ) {
    10741234                add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved);
    10751235                add_comment_meta($comment_id, '_wp_trash_meta_time', time() );
    1076                 do_action('trashed_comment', $comment_id);
     1236
     1237                /**
     1238                 * Fires after a comment is sent to Trash.
     1239                 *
     1240                 * @since 2.9.0
     1241                 *
     1242                 * @param int $comment_id The comment ID.
     1243                 */
     1244                do_action( 'trashed_comment', $comment_id );
    10771245                return true;
    10781246        }
    10791247
     
    10941262        if ( ! (int)$comment_id )
    10951263                return false;
    10961264
    1097         do_action('untrash_comment', $comment_id);
     1265        /**
     1266         * Fires before a comment is restored from Trash.
     1267         *
     1268         * @since 2.9.0
     1269         *
     1270         * @param int $comment_id The comment ID.
     1271         */
     1272        do_action( 'untrash_comment', $comment_id );
    10981273
    10991274        $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true);
    11001275        if ( empty($status) )
     
    11031278        if ( wp_set_comment_status($comment_id, $status) ) {
    11041279                delete_comment_meta($comment_id, '_wp_trash_meta_time');
    11051280                delete_comment_meta($comment_id, '_wp_trash_meta_status');
    1106                 do_action('untrashed_comment', $comment_id);
     1281                /**
     1282                 * Fires after a comment is restored from Trash.
     1283                 *
     1284                 * @since 2.9.0
     1285                 *
     1286                 * @param int $comment_id The comment ID.
     1287                 */
     1288                do_action( 'untrashed_comment', $comment_id );
    11071289                return true;
    11081290        }
    11091291
     
    11241306        if ( !$comment = get_comment($comment_id) )
    11251307                return false;
    11261308
    1127         do_action('spam_comment', $comment_id);
     1309        /**
     1310         * Fires before a comment is marked as Spam.
     1311         *
     1312         * @since 2.9.0
     1313         *
     1314         * @param int $comment_id The comment ID.
     1315         */
     1316        do_action( 'spam_comment', $comment_id );
    11281317
    11291318        if ( wp_set_comment_status($comment_id, 'spam') ) {
    11301319                add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved);
    1131                 do_action('spammed_comment', $comment_id);
     1320                /**
     1321                 * Fires after a comment is marked as Spam.
     1322                 *
     1323                 * @since 2.9.0
     1324                 *
     1325                 * @param int $comment_id The comment ID.
     1326                 */
     1327                do_action( 'spammed_comment', $comment_id );
    11321328                return true;
    11331329        }
    11341330
     
    11491345        if ( ! (int)$comment_id )
    11501346                return false;
    11511347
    1152         do_action('unspam_comment', $comment_id);
     1348        /**
     1349         * Fires before a comment is unmarked as Spam.
     1350         *
     1351         * @since 2.9.0
     1352         *
     1353         * @param int $comment_id The comment ID.
     1354         */
     1355        do_action( 'unspam_comment', $comment_id );
    11531356
    11541357        $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true);
    11551358        if ( empty($status) )
     
    11571360
    11581361        if ( wp_set_comment_status($comment_id, $status) ) {
    11591362                delete_comment_meta($comment_id, '_wp_trash_meta_status');
    1160                 do_action('unspammed_comment', $comment_id);
     1363                /**
     1364                 * Fires after a comment is unmarked as Spam.
     1365                 *
     1366                 * @since 2.9.0
     1367                 *
     1368                 * @param int $comment_id The comment ID.
     1369                 */
     1370                do_action( 'unspammed_comment', $comment_id );
    11611371                return true;
    11621372        }
    11631373
     
    12271437
    12281438        // Call the hooks
    12291439        if ( $new_status != $old_status ) {
    1230                 do_action('transition_comment_status', $new_status, $old_status, $comment);
    1231                 do_action("comment_{$old_status}_to_{$new_status}", $comment);
     1440                /**
     1441                 * Fires
     1442                 *
     1443                 * @since 2.7.0
     1444                 *
     1445                 * @param int|string $new_status The new comment status.
     1446                 * @param int|string $old_status The old comment status.
     1447                 * @param string     $comment    The comment data.
     1448                 */
     1449                do_action( 'transition_comment_status', $new_status, $old_status, $comment );
     1450                /**
     1451                 * Fires
     1452                 *
     1453                 * @since 2.7.0
     1454                 *
     1455                 * @param obj $comment Comment object.
     1456                 */
     1457                do_action( "comment_{$old_status}_to_{$new_status}", $comment );
    12321458        }
    1233         do_action("comment_{$new_status}_{$comment->comment_type}", $comment->comment_ID, $comment);
     1459        /**
     1460         * Fires
     1461         *
     1462         * @since 2.7.0
     1463         *
     1464         * @param int $comment_ID The comment ID.
     1465         * @param obj $comment    Comment object.
     1466         */
     1467        do_action( "comment_{$new_status}_{$comment->comment_type}", $comment->comment_ID, $comment );
    12341468}
    12351469
    12361470/**
     
    12601494        if ( isset($_COOKIE['comment_author_url_'.COOKIEHASH]) )
    12611495                $comment_author_url = $_COOKIE['comment_author_url_'.COOKIEHASH];
    12621496
    1263         return apply_filters('wp_get_current_commenter', compact('comment_author', 'comment_author_email', 'comment_author_url'));
     1497        /**
     1498         * Filter the current commenter's name, email, and URL.
     1499         *
     1500         * @since 3.1.0
     1501         *
     1502         * @param string $comment_author       The comment author's name.
     1503         * @param string $comment_author_email The comment author's email.
     1504         * @param string $comment_author_url   The comment author's URL.
     1505         */
     1506        return apply_filters( 'wp_get_current_commenter', compact('comment_author', 'comment_author_email', 'comment_author_url') );
    12641507}
    12651508
    12661509/**
     
    13051548                wp_update_comment_count($comment_post_ID);
    13061549
    13071550        $comment = get_comment($id);
    1308         do_action('wp_insert_comment', $id, $comment);
    13091551
     1552        /**
     1553         * Fires after the comment is inserted into the database.
     1554         *
     1555         * @since 2.8.0
     1556         *
     1557         * @param int $id      The comment ID.
     1558         * @param obj $comment Comment object.
     1559         */
     1560        do_action( 'wp_insert_comment', $id, $comment );
     1561
    13101562        wp_cache_set( 'last_changed', microtime(), 'comment' );
    13111563
    13121564        return $id;
     
    13331585 */
    13341586function wp_filter_comment($commentdata) {
    13351587        if ( isset($commentdata['user_ID']) )
    1336                 $commentdata['user_id'] = apply_filters('pre_user_id', $commentdata['user_ID']);
     1588                /**
     1589                 * Filter the user ID before it is set.
     1590                 *
     1591                 * @since 1.5.2
     1592                 *
     1593                 * @param int $user_ID The user ID.
     1594                 */
     1595                $commentdata['user_id'] = apply_filters( 'pre_user_id', $commentdata['user_ID'] );
    13371596        elseif ( isset($commentdata['user_id']) )
    1338                 $commentdata['user_id'] = apply_filters('pre_user_id', $commentdata['user_id']);
    1339         $commentdata['comment_agent']        = apply_filters('pre_comment_user_agent', ( isset( $commentdata['comment_agent'] ) ? $commentdata['comment_agent'] : '' ) );
    1340         $commentdata['comment_author']       = apply_filters('pre_comment_author_name', $commentdata['comment_author']);
    1341         $commentdata['comment_content']      = apply_filters('pre_comment_content', $commentdata['comment_content']);
    1342         $commentdata['comment_author_IP']    = apply_filters('pre_comment_user_ip', $commentdata['comment_author_IP']);
    1343         $commentdata['comment_author_url']   = apply_filters('pre_comment_author_url', $commentdata['comment_author_url']);
    1344         $commentdata['comment_author_email'] = apply_filters('pre_comment_author_email', $commentdata['comment_author_email']);
     1597                /** This filter is documented in wp-includes/comment.php */
     1598                $commentdata['user_id'] = apply_filters( 'pre_user_id', $commentdata['user_id'] );
     1599        /**
     1600         * Filter the comment author's browser user agent before it is set.
     1601         *
     1602         * @since 1.5.2
     1603         *
     1604         * @param int $comment_agent The comment author's browser user agent.
     1605         */
     1606        $commentdata['comment_agent']        = apply_filters( 'pre_comment_user_agent', ( isset( $commentdata['comment_agent'] ) ? $commentdata['comment_agent'] : '' ) );
     1607        /** This filter is documented in wp-includes/comment.php */
     1608        $commentdata['comment_author']       = apply_filters( 'pre_comment_author_name', $commentdata['comment_author'] );
     1609        /**
     1610         * Filter the comment content before it is set.
     1611         *
     1612         * @since 1.5.2
     1613         *
     1614         * @param int $comment_content The comment content.
     1615         */
     1616        $commentdata['comment_content']      = apply_filters( 'pre_comment_content', $commentdata['comment_content'] );
     1617        /**
     1618         * Filter the comment author's IP before it is set.
     1619         *
     1620         * @since 1.5.2
     1621         *
     1622         * @param int $comment_author_ip The comment author's IP.
     1623         */
     1624        $commentdata['comment_author_IP']    = apply_filters( 'pre_comment_user_ip', $commentdata['comment_author_IP'] );
     1625        /** This filter is documented in wp-includes/comment.php */
     1626        $commentdata['comment_author_url']   = apply_filters( 'pre_comment_author_url', $commentdata['comment_author_url'] );
     1627        /** This filter is documented in wp-includes/comment.php */
     1628        $commentdata['comment_author_email'] = apply_filters( 'pre_comment_author_email', $commentdata['comment_author_email'] );
    13451629        $commentdata['filtered'] = true;
    13461630        return $commentdata;
    13471631}
     
    13811665 * @return int The ID of the comment after adding.
    13821666 */
    13831667function wp_new_comment( $commentdata ) {
    1384         $commentdata = apply_filters('preprocess_comment', $commentdata);
     1668        /**
     1669         * Filter the comment data before being inserted into the database.
     1670         *
     1671         * @since 1.5.2
     1672         *
     1673         * @param int|string $commentdata The comment data.
     1674         */
     1675        $commentdata = apply_filters( 'preprocess_comment', $commentdata );
    13851676
    13861677        $commentdata['comment_post_ID'] = (int) $commentdata['comment_post_ID'];
    13871678        if ( isset($commentdata['user_ID']) )
     
    14051696
    14061697        $comment_ID = wp_insert_comment($commentdata);
    14071698
    1408         do_action('comment_post', $comment_ID, $commentdata['comment_approved']);
     1699        /**
     1700         * Fires
     1701         *
     1702         * @since 1.2.1
     1703         *
     1704         * @param int    $comment_ID       The comment ID.
     1705         * @param string $comment_approved
     1706         */
     1707        do_action( 'comment_post', $comment_ID, $commentdata['comment_approved'] );
    14091708
    14101709        if ( 'spam' !== $commentdata['comment_approved'] ) { // If it's spam save it silently for later crunching
    14111710                if ( '0' == $commentdata['comment_approved'] ) {
     
    14751774
    14761775        $comment = get_comment($comment_id);
    14771776
    1478         do_action('wp_set_comment_status', $comment_id, $comment_status);
     1777        /**
     1778         * Fires after the comment is handled.
     1779         *
     1780         * This action accepts the following comment status: 'hold', 'approve', 'spam',
     1781         * or 'trash'. If the comment status is not in the list, then false is returned.
     1782         *
     1783         * @since 1.5.2
     1784         *
     1785         * @param int    $comment_id     The comment ID.
     1786         * @param string $comment_status The comment status.
     1787         */
     1788        do_action( 'wp_set_comment_status', $comment_id, $comment_status );
    14791789        wp_transition_comment_status($comment_status, $comment_old->comment_approved, $comment);
    14801790
    14811791        wp_update_comment_count($comment->comment_post_ID);
     
    15161826        // Now extract the merged array.
    15171827        extract(wp_unslash($commentarr), EXTR_SKIP);
    15181828
    1519         $comment_content = apply_filters('comment_save_pre', $comment_content);
     1829        /**
     1830         * Filter the comment content before being updated.
     1831         *
     1832         * @since 1.5.2
     1833         *
     1834         * @param int|string $comment_content The comment data.
     1835         */
     1836        $comment_content = apply_filters( 'comment_save_pre', $comment_content );
    15201837
    15211838        $comment_date_gmt = get_gmt_from_date($comment_date);
    15221839
     
    15321849
    15331850        clean_comment_cache($comment_ID);
    15341851        wp_update_comment_count($comment_post_ID);
    1535         do_action('edit_comment', $comment_ID);
     1852        /**
     1853         * Fires
     1854         *
     1855         * @since 1.2.1
     1856         *
     1857         * @param int $comment_ID The comment ID.
     1858         */
     1859        do_action( 'edit_comment', $comment_ID );
    15361860        $comment = get_comment($comment_ID);
    15371861        wp_transition_comment_status($comment->comment_approved, $old_status, $comment);
    15381862        return $rval;
     
    16291953
    16301954        clean_post_cache( $post );
    16311955
    1632         do_action('wp_update_comment_count', $post_id, $new, $old);
    1633         do_action('edit_post', $post_id, $post);
     1956        /**
     1957         * Fires after updating the comment count.
     1958         *
     1959         * @since 2.3.0
     1960         *
     1961         * @param int $post_id The post ID.
     1962         * @param int $new     The new comment count.
     1963         * @param int $old     The old comment count.
     1964         */
     1965        do_action( 'wp_update_comment_count', $post_id, $new, $old );
     1966        /** This action is documented in wp-includes/post.php */
     1967        do_action( 'edit_post', $post_id, $post );
    16341968
    16351969        return true;
    16361970}
     
    17612095        }
    17622096
    17632097        if ( empty($post->post_excerpt) )
    1764                 $excerpt = apply_filters('the_content', $post->post_content, $post->ID);
     2098                /** This filter is documented in wp-admin/post-template.php */
     2099                $excerpt = apply_filters( 'the_content', $post->post_content, $post->ID );
    17652100        else
    1766                 $excerpt = apply_filters('the_excerpt', $post->post_excerpt);
     2101                /** This filter is documented in wp-admin/post-template.php */
     2102                $excerpt = apply_filters( 'the_excerpt', $post->post_excerpt );
    17672103        $excerpt = str_replace(']]>', ']]&gt;', $excerpt);
    17682104        $excerpt = wp_html_excerpt($excerpt, 252, '&#8230;');
    17692105
    17702106        /** This filter is documented in wp-includes/post-template.php */
    1771         $post_title = apply_filters('the_title', $post->post_title, $post->ID);
     2107        $post_title = apply_filters( 'the_title', $post->post_title, $post->ID );
    17722108        $post_title = strip_tags($post_title);
    17732109
    17742110        if ( $to_ping ) {
     
    18512187        endforeach;
    18522188
    18532189        $post_links = array_unique( $post_links );
     2190        /**
     2191         * Fires
     2192         *
     2193         * @since 2.0.0
     2194         *
     2195         * @param array &$post_links The post links to be checked, passed by reference.
     2196         * @param array &$pung       Whether a link has already been pinged, passed by reference.
     2197         * @param int   $post_ID     The post ID.
     2198         */
    18542199        do_action_ref_array( 'pre_ping', array( &$post_links, &$pung, $post_ID ) );
    18552200
    18562201        foreach ( (array) $post_links as $pagelinkedto ) {
     
    18582203
    18592204                if ( $pingback_server_url ) {
    18602205                        @ set_time_limit( 60 );
    1861                          // Now, the RPC call
     2206                        // Now, the RPC call
    18622207                        $pagelinkedfrom = get_permalink($post_ID);
    18632208
    18642209                        // using a timeout of 3 seconds should be enough to cover slow servers
    18652210                        $client = new WP_HTTP_IXR_Client($pingback_server_url);
    18662211                        $client->timeout = 3;
    1867                         $client->useragent = apply_filters( 'pingback_useragent', $client->useragent . ' -- WordPress/' . $wp_version, $client->useragent, $pingback_server_url, $pagelinkedto, $pagelinkedfrom);
     2212                        /**
     2213                         * Filter the
     2214                         *
     2215                         * @since 2.9.0
     2216                         *
     2217                         * @param int|string $client->useragent . ' -- WordPress/' . $wp_version
     2218                         * @param string     $client->useragent   
     2219                         * @param string     $pingback_server_url The server URL being linked to.
     2220                         * @param string     $pagelinkedto        URL of page linked to.
     2221                         * @param string     $pagelinkedfrom      URL of page linked from.
     2222                         */
     2223                        $client->useragent = apply_filters( 'pingback_useragent', $client->useragent . ' -- WordPress/' . $wp_version, $client->useragent, $pingback_server_url, $pagelinkedto, $pagelinkedfrom );
    18682224                        // when set to true, this outputs debug messages by itself
    18692225                        $client->debug = false;
    18702226
     
    20412397        if ( empty( $posts ) || ! $query->is_singular() || ! get_option( 'close_comments_for_old_posts' ) )
    20422398                return $posts;
    20432399
     2400        /**
     2401         * Filter the post types that comments should be closed on automatically.
     2402         *
     2403         * @since 3.2.0
     2404         *
     2405         * @param array $post_types An array of registered post types. Default 'post'.
     2406         */
    20442407        $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) );
    20452408        if ( ! in_array( $posts[0]->post_type, $post_types ) )
    20462409                return $posts;
     
    20802443
    20812444        $post = get_post($post_id);
    20822445
     2446        /** This filter is documented in wp-includes/comment.php */
    20832447        $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) );
    20842448        if ( ! in_array( $post->post_type, $post_types ) )
    20852449                return $open;