WordPress.org

Make WordPress Core

Changeset 25584


Ignore:
Timestamp:
09/23/2013 09:20:48 PM (7 years ago)
Author:
DrewAPicture
Message:

Inline documentation for hooks in wp-includes/comment-template.php.

Fixes #25396.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/comment-template.php

    r25575 r25584  
    3232    }
    3333
     34    /**
     35     * Filter the returned comment author name.
     36     *
     37     * @since 1.5.2
     38     *
     39     * @param string $author The comment author's username.
     40     */
    3441    return apply_filters( 'get_comment_author', $author );
    3542}
     
    4350 */
    4451function comment_author( $comment_ID = 0 ) {
    45     $author = apply_filters('comment_author', get_comment_author( $comment_ID ) );
     52    $author = get_comment_author( $comment_ID );
     53    /**
     54     * Filter the comment author's name for display.
     55     *
     56     * @since 1.2.1
     57     *
     58     * @param string $author The comment author's username.
     59     */
     60    $author = apply_filters( 'comment_author', $author );
    4661    echo $author;
    4762}
     
    5772function get_comment_author_email( $comment_ID = 0 ) {
    5873    $comment = get_comment( $comment_ID );
    59     return apply_filters('get_comment_author_email', $comment->comment_author_email);
     74    /**
     75     * Filter the comment author's returned email address.
     76     *
     77     * @since 1.5.2
     78     *
     79     * @param string $comment->comment_author_email The comment author's email address.
     80     */
     81    return apply_filters( 'get_comment_author_email', $comment->comment_author_email );
    6082}
    6183
     
    7496 */
    7597function comment_author_email( $comment_ID = 0 ) {
    76     echo apply_filters('author_email', get_comment_author_email( $comment_ID ) );
     98    $author_email = get_comment_author_email( $comment_ID );
     99    /**
     100     * Filter the comment author's email for display.
     101     *
     102     * @since 1.2.1
     103     *
     104     * @param string $author_email The comment author's email address.
     105     */
     106    echo apply_filters( 'author_email', $author_email );
    77107}
    78108
     
    118148function get_comment_author_email_link( $linktext = '', $before = '', $after = '' ) {
    119149    global $comment;
    120     $email = apply_filters('comment_email', $comment->comment_author_email);
     150    /**
     151     * Filter the comment author's email for display.
     152     *
     153     * Care should be taken to protect the email address and assure that email
     154     * harvesters do not capture your commentors' email address.
     155     *
     156     * @since 1.2.1
     157     *
     158     * @param string $comment->comment_author_email The comment author's email address.
     159     */
     160    $email = apply_filters( 'comment_email', $comment->comment_author_email );
    121161    if ((!empty($email)) && ($email != '@')) {
    122162    $display = ($linktext != '') ? $linktext : $email;
     
    149189    else
    150190        $return = "<a href='$url' rel='external nofollow' class='url'>$author</a>";
    151     return apply_filters('get_comment_author_link', $return);
     191
     192    /**
     193     * Filter the comment author's link for display.
     194     *
     195     * @since 1.5.2
     196     *
     197     * @param string $return The HTML-formatted comment author link. Empty for an invalid URL.
     198     */
     199    return apply_filters( 'get_comment_author_link', $return );
    152200}
    153201
     
    174222function get_comment_author_IP( $comment_ID = 0 ) {
    175223    $comment = get_comment( $comment_ID );
    176     return apply_filters('get_comment_author_IP', $comment->comment_author_IP);
     224
     225    /**
     226     * Filter the comment author's returned IP address.
     227     *
     228     * @since 1.5.2
     229     *
     230     * @param string $comment->comment_author_IP The comment author's IP address.
     231     */
     232    return apply_filters( 'get_comment_author_IP', $comment->comment_author_IP );
    177233}
    178234
     
    211267 */
    212268function comment_author_url( $comment_ID = 0 ) {
    213     echo apply_filters('comment_url', get_comment_author_url( $comment_ID ));
     269    $author_url = get_comment_author_url( $comment_ID );
     270    /**
     271     * Filter the comment author's URL for display.
     272     *
     273     * @since 1.2.1
     274     *
     275     * @param string $author_url The comment author's URL.
     276     */
     277    echo apply_filters( 'comment_url', $author_url );
    214278}
    215279
     
    239303        $display = substr($display, 0, -1);
    240304    $return = "$before<a href='$url' rel='external'>$display</a>$after";
    241     return apply_filters('get_comment_author_url_link', $return);
     305
     306    /**
     307     * Filter the comment author's returned URL link.
     308     *
     309     * @since 1.5.2
     310     *
     311     * @param string $return The HTML-formatted comment author URL link.
     312     */
     313    return apply_filters( 'get_comment_author_url_link', $return );
    242314}
    243315
     
    343415    $classes = array_map('esc_attr', $classes);
    344416
    345     return apply_filters('comment_class', $classes, $class, $comment_id, $post_id);
     417    /**
     418     * Filter the returned CSS classes for the current comment.
     419     *
     420     * @since 2.7.0
     421     *
     422     * @param array       $classes    An array of comment classes.
     423     * @param string      $class      A comma-separated list of additional classes added to the list.
     424     * @param int         $comment_id The comment id.
     425     * @param int|WP_Post $post_id    The post ID or WP_Post object.
     426     */
     427    return apply_filters( 'comment_class', $classes, $class, $comment_id, $post_id );
    346428}
    347429
     
    361443    else
    362444        $date = mysql2date($d, $comment->comment_date);
    363     return apply_filters('get_comment_date', $date, $d);
     445    /**
     446     * Filter the returned comment date.
     447     *
     448     * @since 1.5.2
     449     *
     450     * @param string|int $date Formatted date string or Unix timestamp.
     451     * @param string     $d    The format of the date.
     452     */
     453    return apply_filters( 'get_comment_date', $date, $d );
    364454}
    365455
     
    415505 */
    416506function comment_excerpt( $comment_ID = 0 ) {
    417     echo apply_filters('comment_excerpt', get_comment_excerpt($comment_ID) );
     507    $comment_excerpt = get_comment_excerpt($comment_ID);
     508    /**
     509     * Filter the comment excerpt for display.
     510     *
     511     * @since 1.2.1
     512     *
     513     * @param string $comment_excerpt The comment excerpt text.
     514     */
     515    echo apply_filters( 'comment_excerpt', $comment_excerpt );
    418516}
    419517
     
    427525function get_comment_ID() {
    428526    global $comment;
    429     return apply_filters('get_comment_ID', $comment->comment_ID);
     527    /**
     528     * Filter the returned comment ID.
     529     *
     530     * @since 1.5.2
     531     *
     532     * @param int $comment->comment_ID The current comment ID.
     533     */
     534    return apply_filters( 'get_comment_ID', $comment->comment_ID );
    430535}
    431536
     
    483588    }
    484589
    485     return apply_filters( 'get_comment_link', $link . '#comment-' . $comment->comment_ID, $comment, $args );
     590    $link = $link . '#comment-' . $comment->comment_ID;
     591    /**
     592     * Filter the returned single comment permalink.
     593     *
     594     * @since 2.8.0
     595     *
     596     * @param string $link    The comment permalink with '#comment-$id' appended.
     597     * @param object $comment The current comment object.
     598     * @param array  $args    An array of arguments to override the defaults. @see get_page_of_comment()
     599     */
     600    return apply_filters( 'get_comment_link', $link, $comment, $args );
    486601}
    487602
     
    495610 */
    496611function get_comments_link( $post_id = 0 ) {
    497     return apply_filters( 'get_comments_link', get_permalink( $post_id ) . '#comments', $post_id );
     612    $comments_link = get_permalink( $post_id ) . '#comments';
     613    /**
     614     * Filter the returned post comments permalink.
     615     *
     616     * @since
     617     *
     618     * @param string      $comments_link The post comments permalink with '#comments' appended.
     619     * @param int|WP_Post $post_id       The post ID or WP_Post object.
     620     */
     621    return apply_filters( 'get_comments_link', $comments_link, $post_id );
    498622}
    499623
     
    534658        $count = $post->comment_count;
    535659
    536     return apply_filters('get_comments_number', $count, $post_id);
     660    /**
     661     * Filter the returned comment count for a post.
     662     *
     663     * @since 1.5.2
     664     *
     665     * @param int         $count   The number of comments a post has.
     666     * @param int|WP_Post $post_id The post ID or WP_Post object.
     667     */
     668    return apply_filters( 'get_comments_number', $count, $post_id );
    537669}
    538670
     
    560692        $output = ( false === $one ) ? __('1 Comment') : $one;
    561693
    562     echo apply_filters('comments_number', $output, $number);
     694    /**
     695     * Filter the comments count for display.
     696     *
     697     * @since 1.5.2
     698     *
     699     * @param string $output A translatable string formatted based on whether the count is equal to 0, 1, or 1+. @see _n()
     700     * @param int    $number The number of post comments.
     701     */
     702    echo apply_filters( 'comments_number', $output, $number );
    563703}
    564704
     
    630770    else
    631771        $date = mysql2date($d, $comment_date, $translate);
    632     return apply_filters('get_comment_time', $date, $d, $gmt, $translate);
     772
     773    /**
     774     * Filter the returned comment time.
     775     *
     776     * @since 1.5.2
     777     *
     778     * @param string|int $date      The comment time, formatted as a date string or Unix timestamp.
     779     * @param string     $d         The date format.
     780     * @param bool       $gmt       Whether the GMT date is in use.
     781     * @param bool       $translate Whether the time is translated.
     782     */
     783    return apply_filters( 'get_comment_time', $date, $d, $gmt, $translate );
    633784}
    634785
     
    657808        $comment->comment_type = 'comment';
    658809
    659     return apply_filters('get_comment_type', $comment->comment_type);
     810    /**
     811     * Filter the returned comment type.
     812     *
     813     * @since 1.5.2
     814     *
     815     * @param string $comment->comment_type The type of comment, such as 'comment', 'pingback', or 'trackback'.
     816     */
     817    return apply_filters( 'get_comment_type', $comment->comment_type );
    660818}
    661819
     
    698856 */
    699857function get_trackback_url() {
    700     if ( '' != get_option('permalink_structure') ) {
     858    if ( '' != get_option('permalink_structure') )
    701859        $tb_url = trailingslashit(get_permalink()) . user_trailingslashit('trackback', 'single_trackback');
    702     } else {
     860    else
    703861        $tb_url = get_option('siteurl') . '/wp-trackback.php?p=' . get_the_ID();
    704     }
    705     return apply_filters('trackback_url', $tb_url);
     862
     863    /**
     864     * Filter the returned trackback URL.
     865     *
     866     * @since 2.2.0
     867     *
     868     * @param string $tb_url The trackback URL.
     869     */
     870    return apply_filters( 'trackback_url', $tb_url );
    706871}
    707872
     
    766931
    767932    $open = ( 'open' == $_post->comment_status );
     933
     934    /**
     935     * Filter whether the current post is open for comments.
     936     *
     937     * @since
     938     *
     939     * @param bool        $open    Whether the current post is open for comments.
     940     * @param int|WP_Post $post_id The post ID or WP_Post object.
     941     */
    768942    return apply_filters( 'comments_open', $open, $post_id );
    769943}
     
    8771051
    8781052    // keep $comments for legacy's sake
     1053    /**
     1054     * Filter the comments array.
     1055     *
     1056     * @since 2.1.0
     1057     *
     1058     * @param array $comments The array of comments supplied to the comments template.
     1059     * @param int   $post->ID The post ID.
     1060     */
    8791061    $wp_query->comments = apply_filters( 'comments_array', $comments, $post->ID );
    8801062    $comments = &$wp_query->comments;
     
    8961078        define('COMMENTS_TEMPLATE', true);
    8971079
    898     $include = apply_filters('comments_template', STYLESHEETPATH . $file );
     1080    $theme_template = STYLESHEETPATH . $file;
     1081    /**
     1082     * Filter the path to the theme template file used for the comments template.
     1083     *
     1084     * @since 1.5.2
     1085     *
     1086     * @param string $theme_template The path to the theme template file.
     1087     */
     1088    $include = apply_filters( 'comments_template', $theme_template );
    8991089    if ( file_exists( $include ) )
    9001090        require( $include );
     
    9981188    $title = the_title_attribute( array('echo' => 0 ) );
    9991189
    1000     echo apply_filters( 'comments_popup_link_attributes', '' );
     1190    $attributes = '';
     1191    /**
     1192     * Filter the comments popup link attributes for display.
     1193     *
     1194     * @since 2.5.0
     1195     *
     1196     * @param string $attributes The comments popup link attributes. Default empty.
     1197     */
     1198    echo apply_filters( 'comments_popup_link_attributes', $attributes );
    10011199
    10021200    echo ' title="' . esc_attr( sprintf( __('Comment on %s'), $title ) ) . '">';
     
    11311329        return false;
    11321330
    1133     if ( get_option('comment_registration') && ! is_user_logged_in() ) {
     1331    if ( get_option('comment_registration') && ! is_user_logged_in() )
    11341332        $link = '<a rel="nofollow" href="' . wp_login_url( get_permalink() ) . '">' . $login_text . '</a>';
    1135     } else {
     1333    else
    11361334        $link = "<a rel='nofollow' class='comment-reply-link' href='" . get_permalink($post->ID) . "#$respond_id' onclick='return addComment.moveForm(\"$add_below-$post->ID\", \"0\", \"$respond_id\", \"$post->ID\")'>$reply_text</a>";
    1137     }
    1138     return apply_filters('post_comments_link', $before . $link . $after, $post);
     1335
     1336    $formatted_link = $before . $link . $after;
     1337    /**
     1338     * Filter the formatted post comments link HTML.
     1339     *
     1340     * @since 2.7.0
     1341     *
     1342     * @param string      $formatted The HTML-formatted post comments link.
     1343     * @param int|WP_Post $post      The post ID or WP_Post object.
     1344     */
     1345    return apply_filters( 'post_comments_link', $formatted_link, $post );
    11391346}
    11401347
     
    11651372    $style = isset($_GET['replytocom']) ? '' : ' style="display:none;"';
    11661373    $link = esc_html( remove_query_arg('replytocom') ) . '#respond';
    1167     return apply_filters('cancel_comment_reply_link', '<a rel="nofollow" id="cancel-comment-reply-link" href="' . $link . '"' . $style . '>' . $text . '</a>', $link, $text);
     1374
     1375    $formatted_link = '<a rel="nofollow" id="cancel-comment-reply-link" href="' . $link . '"' . $style . '>' . $text . '</a>';
     1376    /**
     1377     * Filter the cancel comment reply link HTML.
     1378     *
     1379     * @since 2.7.0
     1380     *
     1381     * @param string $formatted_link The HTML-formatted cancel comment reply link.
     1382     * @param string $link           The cancel comment reply link URL.
     1383     * @param string $text           The cancel comment reply link text.
     1384     */
     1385    return apply_filters( 'cancel_comment_reply_link', $formatted_link, $link, $text );
    11681386}
    11691387
     
    11941412    $result  = "<input type='hidden' name='comment_post_ID' value='$id' id='comment_post_ID' />\n";
    11951413    $result .= "<input type='hidden' name='comment_parent' id='comment_parent' value='$replytoid' />\n";
    1196     return apply_filters('comment_id_fields', $result, $id, $replytoid);
     1414
     1415    /**
     1416     * Filter the returned comment id fields.
     1417     *
     1418     * @since 3.0.0
     1419     *
     1420     * @param string $result    The HTML-formatted hidden id field comment elements.
     1421     * @param int    $id        The post ID.
     1422     * @param int    $replytoid The id of the comment being replied to.
     1423     */
     1424    return apply_filters( 'comment_id_fields', $result, $id, $replytoid );
    11971425}
    11981426
     
    16961924
    16971925    $required_text = sprintf( ' ' . __('Required fields are marked %s'), '<span class="required">*</span>' );
     1926
     1927    /**
     1928     * Filter the default comment form fields.
     1929     *
     1930     * @since 3.0.0
     1931     *
     1932     * @param array $fields The default comment fields.
     1933     */
     1934    $fields = apply_filters( 'comment_form_default_fields', $fields );
    16981935    $defaults = array(
    1699         'fields'               => apply_filters( 'comment_form_default_fields', $fields ),
     1936        'fields'               => $fields,
    17001937        'comment_field'        => '<p class="comment-form-comment"><label for="comment">' . _x( 'Comment', 'noun' ) . '</label> <textarea id="comment" name="comment" cols="45" rows="8" aria-required="true"></textarea></p>',
    17011938        'must_log_in'          => '<p class="must-log-in">' . sprintf( __( 'You must be <a href="%s">logged in</a> to post a comment.' ), wp_login_url( apply_filters( 'the_permalink', get_permalink( $post_id ) ) ) ) . '</p>',
     
    17121949    );
    17131950
     1951    /**
     1952     * Filter the comment form default arguments.
     1953     *
     1954     * Use 'comment_form_default_fields' to filter the comment fields.
     1955     *
     1956     * @since 3.0.0
     1957     *
     1958     * @param array $defaults The default comment form arguments.
     1959     */
    17141960    $args = wp_parse_args( $args, apply_filters( 'comment_form_defaults', $defaults ) );
    17151961
    17161962    ?>
    17171963        <?php if ( comments_open( $post_id ) ) : ?>
    1718             <?php do_action( 'comment_form_before' ); ?>
     1964            <?php
     1965            /**
     1966             * Fires before the comment form.
     1967             *
     1968             * @since 3.0.0
     1969             */
     1970            do_action( 'comment_form_before' );
     1971            ?>
    17191972            <div id="respond" class="comment-respond">
    17201973                <h3 id="reply-title" class="comment-reply-title"><?php comment_form_title( $args['title_reply'], $args['title_reply_to'] ); ?> <small><?php cancel_comment_reply_link( $args['cancel_reply_link'] ); ?></small></h3>
    17211974                <?php if ( get_option( 'comment_registration' ) && !is_user_logged_in() ) : ?>
    17221975                    <?php echo $args['must_log_in']; ?>
    1723                     <?php do_action( 'comment_form_must_log_in_after' ); ?>
     1976                    <?php
     1977                    /**
     1978                     * Fires after the HTML-formatted 'must log in after' message in the comment form.
     1979                     *
     1980                     * @since 3.0.0
     1981                     */
     1982                    do_action( 'comment_form_must_log_in_after' );
     1983                    ?>
    17241984                <?php else : ?>
    17251985                    <form action="<?php echo site_url( '/wp-comments-post.php' ); ?>" method="post" id="<?php echo esc_attr( $args['id_form'] ); ?>" class="comment-form"<?php echo $html5 ? ' novalidate' : ''; ?>>
    1726                         <?php do_action( 'comment_form_top' ); ?>
     1986                        <?php
     1987                        /**
     1988                         * Fires at the top of the comment form, inside the <form> tag.
     1989                         *
     1990                         * @since 3.0.0
     1991                         */
     1992                        do_action( 'comment_form_top' );
     1993                        ?>
    17271994                        <?php if ( is_user_logged_in() ) : ?>
    1728                             <?php echo apply_filters( 'comment_form_logged_in', $args['logged_in_as'], $commenter, $user_identity ); ?>
    1729                             <?php do_action( 'comment_form_logged_in_after', $commenter, $user_identity ); ?>
     1995                            <?php
     1996                            /**
     1997                             * Filter the 'logged in' message for the comment form for display.
     1998                             *
     1999                             * @since 3.0.0
     2000                             *
     2001                             * @param string $args['logged_in_as'] The logged-in-as HTML-formatted message.
     2002                             * @param array  $commenter            An array containing the comment author's username, email, and URL.
     2003                             * @param string $user_identity        If the commenter is a registered user, the display name, blank otherwise.
     2004                             */
     2005                            echo apply_filters( 'comment_form_logged_in', $args['logged_in_as'], $commenter, $user_identity );
     2006                            ?>
     2007                            <?php
     2008                            /**
     2009                             * Fires after the is_user_logged_in() check in the comment form.
     2010                             *
     2011                             * @since 3.0.0
     2012                             *
     2013                             * @param array  $commenter     An array containing the comment author's username, email, and URL.
     2014                             * @param string $user_identity If the commenter is a registered user, the display name, blank otherwise.
     2015                             */
     2016                            do_action( 'comment_form_logged_in_after', $commenter, $user_identity );
     2017                            ?>
    17302018                        <?php else : ?>
    17312019                            <?php echo $args['comment_notes_before']; ?>
    17322020                            <?php
     2021                            /**
     2022                             * Fires before the comment fields in the comment form.
     2023                             *
     2024                             * @since 3.0.0
     2025                             */
    17332026                            do_action( 'comment_form_before_fields' );
    17342027                            foreach ( (array) $args['fields'] as $name => $field ) {
     2028                                /**
     2029                                 * Filter a comment form field for display.
     2030                                 *
     2031                                 * The dynamic portion of the filter hook, $name, refers to the name
     2032                                 * of the comment form field. Such as 'author', 'email', or 'url'.
     2033                                 *
     2034                                 * @since 3.0.0
     2035                                 *
     2036                                 * @param string $field The HTML-formatted output of the comment form field.
     2037                                 */
    17352038                                echo apply_filters( "comment_form_field_{$name}", $field ) . "\n";
    17362039                            }
     2040                            /**
     2041                             * Fires after the comment fields in the comment form.
     2042                             *
     2043                             * @since 3.0.0
     2044                             */
    17372045                            do_action( 'comment_form_after_fields' );
    17382046                            ?>
    17392047                        <?php endif; ?>
    1740                         <?php echo apply_filters( 'comment_form_field_comment', $args['comment_field'] ); ?>
     2048                        <?php
     2049                        /**
     2050                         * Filter the content of the comment textarea field for display.
     2051                         *
     2052                         * @since 3.0.0
     2053                         *
     2054                         * @param string $args['comment_field'] The content of the comment textarea field.
     2055                         */
     2056                        echo apply_filters( 'comment_form_field_comment', $args['comment_field'] );
     2057                        ?>
    17412058                        <?php echo $args['comment_notes_after']; ?>
    17422059                        <p class="form-submit">
     
    17442061                            <?php comment_id_fields( $post_id ); ?>
    17452062                        </p>
    1746                         <?php do_action( 'comment_form', $post_id ); ?>
     2063                        <?php
     2064                        /**
     2065                         * Fires at the bottom of the comment form, inside the closing </form> tag.
     2066                         *
     2067                         * @since 1.5.2
     2068                         *
     2069                         * @param int $post_id The post ID.
     2070                         */
     2071                        do_action( 'comment_form', $post_id );
     2072                        ?>
    17472073                    </form>
    17482074                <?php endif; ?>
    17492075            </div><!-- #respond -->
    1750             <?php do_action( 'comment_form_after' ); ?>
    1751         <?php else : ?>
    1752             <?php do_action( 'comment_form_comments_closed' ); ?>
    1753         <?php endif; ?>
    1754     <?php
    1755 }
     2076            <?php
     2077            /**
     2078             * Fires after the comment form.
     2079             *
     2080             * @since 3.0.0
     2081             */
     2082            do_action( 'comment_form_after' );
     2083        else :
     2084            /**
     2085             * Fires after the comment form if comments are closed.
     2086             *
     2087             * @since 3.0.0
     2088             */
     2089            do_action( 'comment_form_comments_closed' );
     2090        endif;
     2091}
Note: See TracChangeset for help on using the changeset viewer.