Changeset 25584

Timestamp:

09/23/2013 09:20:48 PM (12 years ago)

Author:

DrewAPicture

Message:

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

Fixes #25396.

File:

• trunk/src/wp-includes/comment-template.php (modified) (30 diffs)

trunk/src/wp-includes/comment-template.php

@@ -32 +32 @@
     }
 
+    /**
+     * Filter the returned comment author name.
+     *
+     * @since 1.5.2
+     *
+     * @param string $author The comment author's username.
+     */
     return apply_filters( 'get_comment_author', $author );
 }
@@ -43 +50 @@
  */
 function comment_author( $comment_ID = 0 ) {
-    $author = apply_filters('comment_author', get_comment_author( $comment_ID ) );
+    $author = get_comment_author( $comment_ID );
+    /**
+     * Filter the comment author's name for display.
+     *
+     * @since 1.2.1
+     *
+     * @param string $author The comment author's username.
+     */
+    $author = apply_filters( 'comment_author', $author );
     echo $author;
 }
@@ -57 +72 @@
 function get_comment_author_email( $comment_ID = 0 ) {
     $comment = get_comment( $comment_ID );
-    return apply_filters('get_comment_author_email', $comment->comment_author_email);
+    /**
+     * Filter the comment author's returned email address.
+     *
+     * @since 1.5.2
+     *
+     * @param string $comment->comment_author_email The comment author's email address.
+     */
+    return apply_filters( 'get_comment_author_email', $comment->comment_author_email );
 }
 
@@ -74 +96 @@
  */
 function comment_author_email( $comment_ID = 0 ) {
-    echo apply_filters('author_email', get_comment_author_email( $comment_ID ) );
+    $author_email = get_comment_author_email( $comment_ID );
+    /**
+     * Filter the comment author's email for display.
+     *
+     * @since 1.2.1
+     *
+     * @param string $author_email The comment author's email address.
+     */
+    echo apply_filters( 'author_email', $author_email );
 }
 
@@ -118 +148 @@
 function get_comment_author_email_link( $linktext = '', $before = '', $after = '' ) {
     global $comment;
-    $email = apply_filters('comment_email', $comment->comment_author_email);
+    /**
+     * Filter the comment author's email for display.
+     *
+     * Care should be taken to protect the email address and assure that email
+     * harvesters do not capture your commentors' email address.
+     *
+     * @since 1.2.1
+     *
+     * @param string $comment->comment_author_email The comment author's email address.
+     */
+    $email = apply_filters( 'comment_email', $comment->comment_author_email );
     if ((!empty($email)) && ($email != '@')) {
     $display = ($linktext != '') ? $linktext : $email;
@@ -149 +189 @@
     else
         $return = "<a href='$url' rel='external nofollow' class='url'>$author</a>";
-    return apply_filters('get_comment_author_link', $return);
+
+    /**
+     * Filter the comment author's link for display.
+     *
+     * @since 1.5.2
+     *
+     * @param string $return The HTML-formatted comment author link. Empty for an invalid URL.
+     */
+    return apply_filters( 'get_comment_author_link', $return );
 }
 
@@ -174 +222 @@
 function get_comment_author_IP( $comment_ID = 0 ) {
     $comment = get_comment( $comment_ID );
-    return apply_filters('get_comment_author_IP', $comment->comment_author_IP);
+
+    /**
+     * Filter the comment author's returned IP address.
+     *
+     * @since 1.5.2
+     *
+     * @param string $comment->comment_author_IP The comment author's IP address.
+     */
+    return apply_filters( 'get_comment_author_IP', $comment->comment_author_IP );
 }
 
@@ -211 +267 @@
  */
 function comment_author_url( $comment_ID = 0 ) {
-    echo apply_filters('comment_url', get_comment_author_url( $comment_ID ));
+    $author_url = get_comment_author_url( $comment_ID );
+    /**
+     * Filter the comment author's URL for display.
+     *
+     * @since 1.2.1
+     *
+     * @param string $author_url The comment author's URL.
+     */
+    echo apply_filters( 'comment_url', $author_url );
 }
 
@@ -239 +303 @@
         $display = substr($display, 0, -1);
     $return = "$before<a href='$url' rel='external'>$display</a>$after";
-    return apply_filters('get_comment_author_url_link', $return);
+
+    /**
+     * Filter the comment author's returned URL link.
+     *
+     * @since 1.5.2
+     *
+     * @param string $return The HTML-formatted comment author URL link.
+     */
+    return apply_filters( 'get_comment_author_url_link', $return );
 }
 
@@ -343 +415 @@
     $classes = array_map('esc_attr', $classes);
 
-    return apply_filters('comment_class', $classes, $class, $comment_id, $post_id);
+    /**
+     * Filter the returned CSS classes for the current comment.
+     *
+     * @since 2.7.0
+     *
+     * @param array       $classes    An array of comment classes.
+     * @param string      $class      A comma-separated list of additional classes added to the list.
+     * @param int         $comment_id The comment id.
+     * @param int|WP_Post $post_id    The post ID or WP_Post object.
+     */
+    return apply_filters( 'comment_class', $classes, $class, $comment_id, $post_id );
 }
 
@@ -361 +443 @@
     else
         $date = mysql2date($d, $comment->comment_date);
-    return apply_filters('get_comment_date', $date, $d);
+    /**
+     * Filter the returned comment date.
+     *
+     * @since 1.5.2
+     *
+     * @param string|int $date Formatted date string or Unix timestamp.
+     * @param string     $d    The format of the date.
+     */
+    return apply_filters( 'get_comment_date', $date, $d );
 }
 
@@ -415 +505 @@
  */
 function comment_excerpt( $comment_ID = 0 ) {
-    echo apply_filters('comment_excerpt', get_comment_excerpt($comment_ID) );
+    $comment_excerpt = get_comment_excerpt($comment_ID);
+    /**
+     * Filter the comment excerpt for display.
+     *
+     * @since 1.2.1
+     *
+     * @param string $comment_excerpt The comment excerpt text.
+     */
+    echo apply_filters( 'comment_excerpt', $comment_excerpt );
 }
 
@@ -427 +525 @@
 function get_comment_ID() {
     global $comment;
-    return apply_filters('get_comment_ID', $comment->comment_ID);
+    /**
+     * Filter the returned comment ID.
+     *
+     * @since 1.5.2
+     *
+     * @param int $comment->comment_ID The current comment ID.
+     */
+    return apply_filters( 'get_comment_ID', $comment->comment_ID );
 }
 
@@ -483 +588 @@
     }
 
-    return apply_filters( 'get_comment_link', $link . '#comment-' . $comment->comment_ID, $comment, $args );
+    $link = $link . '#comment-' . $comment->comment_ID;
+    /**
+     * Filter the returned single comment permalink.
+     *
+     * @since 2.8.0
+     *
+     * @param string $link    The comment permalink with '#comment-$id' appended.
+     * @param object $comment The current comment object.
+     * @param array  $args    An array of arguments to override the defaults. @see get_page_of_comment()
+     */
+    return apply_filters( 'get_comment_link', $link, $comment, $args );
 }
 
@@ -495 +610 @@
  */
 function get_comments_link( $post_id = 0 ) {
-    return apply_filters( 'get_comments_link', get_permalink( $post_id ) . '#comments', $post_id );
+    $comments_link = get_permalink( $post_id ) . '#comments';
+    /**
+     * Filter the returned post comments permalink.
+     *
+     * @since
+     *
+     * @param string      $comments_link The post comments permalink with '#comments' appended.
+     * @param int|WP_Post $post_id       The post ID or WP_Post object.
+     */
+    return apply_filters( 'get_comments_link', $comments_link, $post_id );
 }
 
@@ -534 +658 @@
         $count = $post->comment_count;
 
-    return apply_filters('get_comments_number', $count, $post_id);
+    /**
+     * Filter the returned comment count for a post.
+     *
+     * @since 1.5.2
+     *
+     * @param int         $count   The number of comments a post has.
+     * @param int|WP_Post $post_id The post ID or WP_Post object.
+     */
+    return apply_filters( 'get_comments_number', $count, $post_id );
 }
 
@@ -560 +692 @@
         $output = ( false === $one ) ? __('1 Comment') : $one;
 
-    echo apply_filters('comments_number', $output, $number);
+    /**
+     * Filter the comments count for display.
+     *
+     * @since 1.5.2
+     *
+     * @param string $output A translatable string formatted based on whether the count is equal to 0, 1, or 1+. @see _n()
+     * @param int    $number The number of post comments.
+     */
+    echo apply_filters( 'comments_number', $output, $number );
 }
 
@@ -630 +770 @@
     else
         $date = mysql2date($d, $comment_date, $translate);
-    return apply_filters('get_comment_time', $date, $d, $gmt, $translate);
+
+    /**
+     * Filter the returned comment time.
+     *
+     * @since 1.5.2
+     *
+     * @param string|int $date      The comment time, formatted as a date string or Unix timestamp.
+     * @param string     $d         The date format.
+     * @param bool       $gmt       Whether the GMT date is in use.
+     * @param bool       $translate Whether the time is translated.
+     */
+    return apply_filters( 'get_comment_time', $date, $d, $gmt, $translate );
 }
 
@@ -657 +808 @@
         $comment->comment_type = 'comment';
 
-    return apply_filters('get_comment_type', $comment->comment_type);
+    /**
+     * Filter the returned comment type.
+     *
+     * @since 1.5.2
+     *
+     * @param string $comment->comment_type The type of comment, such as 'comment', 'pingback', or 'trackback'.
+     */
+    return apply_filters( 'get_comment_type', $comment->comment_type );
 }
 
@@ -698 +856 @@
  */
 function get_trackback_url() {
-    if ( '' != get_option('permalink_structure') ) {
+    if ( '' != get_option('permalink_structure') )
         $tb_url = trailingslashit(get_permalink()) . user_trailingslashit('trackback', 'single_trackback');
-    } else {
+    else
         $tb_url = get_option('siteurl') . '/wp-trackback.php?p=' . get_the_ID();
-    }
-    return apply_filters('trackback_url', $tb_url);
+
+    /**
+     * Filter the returned trackback URL.
+     *
+     * @since 2.2.0
+     *
+     * @param string $tb_url The trackback URL.
+     */
+    return apply_filters( 'trackback_url', $tb_url );
 }
 
@@ -766 +931 @@
 
     $open = ( 'open' == $_post->comment_status );
+
+    /**
+     * Filter whether the current post is open for comments.
+     *
+     * @since
+     *
+     * @param bool        $open    Whether the current post is open for comments.
+     * @param int|WP_Post $post_id The post ID or WP_Post object.
+     */
     return apply_filters( 'comments_open', $open, $post_id );
 }
@@ -877 +1051 @@
 
     // keep $comments for legacy's sake
+    /**
+     * Filter the comments array.
+     *
+     * @since 2.1.0
+     *
+     * @param array $comments The array of comments supplied to the comments template.
+     * @param int   $post->ID The post ID.
+     */
     $wp_query->comments = apply_filters( 'comments_array', $comments, $post->ID );
     $comments = &$wp_query->comments;
@@ -896 +1078 @@
         define('COMMENTS_TEMPLATE', true);
 
-    $include = apply_filters('comments_template', STYLESHEETPATH . $file );
+    $theme_template = STYLESHEETPATH . $file;
+    /**
+     * Filter the path to the theme template file used for the comments template.
+     *
+     * @since 1.5.2
+     *
+     * @param string $theme_template The path to the theme template file.
+     */
+    $include = apply_filters( 'comments_template', $theme_template );
     if ( file_exists( $include ) )
         require( $include );
@@ -998 +1188 @@
     $title = the_title_attribute( array('echo' => 0 ) );
 
-    echo apply_filters( 'comments_popup_link_attributes', '' );
+    $attributes = '';
+    /**
+     * Filter the comments popup link attributes for display.
+     *
+     * @since 2.5.0
+     *
+     * @param string $attributes The comments popup link attributes. Default empty.
+     */
+    echo apply_filters( 'comments_popup_link_attributes', $attributes );
 
     echo ' title="' . esc_attr( sprintf( __('Comment on %s'), $title ) ) . '">';
@@ -1131 +1329 @@
         return false;
 
-    if ( get_option('comment_registration') && ! is_user_logged_in() ) {
+    if ( get_option('comment_registration') && ! is_user_logged_in() )
         $link = '<a rel="nofollow" href="' . wp_login_url( get_permalink() ) . '">' . $login_text . '</a>';
-    } else {
+    else
         $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>";
-    }
-    return apply_filters('post_comments_link', $before . $link . $after, $post);
+
+    $formatted_link = $before . $link . $after;
+    /**
+     * Filter the formatted post comments link HTML.
+     *
+     * @since 2.7.0
+     *
+     * @param string      $formatted The HTML-formatted post comments link.
+     * @param int|WP_Post $post      The post ID or WP_Post object.
+     */
+    return apply_filters( 'post_comments_link', $formatted_link, $post );
 }
 
@@ -1165 +1372 @@
     $style = isset($_GET['replytocom']) ? '' : ' style="display:none;"';
     $link = esc_html( remove_query_arg('replytocom') ) . '#respond';
-    return apply_filters('cancel_comment_reply_link', '<a rel="nofollow" id="cancel-comment-reply-link" href="' . $link . '"' . $style . '>' . $text . '</a>', $link, $text);
+
+    $formatted_link = '<a rel="nofollow" id="cancel-comment-reply-link" href="' . $link . '"' . $style . '>' . $text . '</a>';
+    /**
+     * Filter the cancel comment reply link HTML.
+     *
+     * @since 2.7.0
+     *
+     * @param string $formatted_link The HTML-formatted cancel comment reply link.
+     * @param string $link           The cancel comment reply link URL.
+     * @param string $text           The cancel comment reply link text.
+     */
+    return apply_filters( 'cancel_comment_reply_link', $formatted_link, $link, $text );
 }
 
@@ -1194 +1412 @@
     $result  = "<input type='hidden' name='comment_post_ID' value='$id' id='comment_post_ID' />\n";
     $result .= "<input type='hidden' name='comment_parent' id='comment_parent' value='$replytoid' />\n";
-    return apply_filters('comment_id_fields', $result, $id, $replytoid);
+
+    /**
+     * Filter the returned comment id fields.
+     *
+     * @since 3.0.0
+     *
+     * @param string $result    The HTML-formatted hidden id field comment elements.
+     * @param int    $id        The post ID.
+     * @param int    $replytoid The id of the comment being replied to.
+     */
+    return apply_filters( 'comment_id_fields', $result, $id, $replytoid );
 }
 
@@ -1696 +1924 @@
 
     $required_text = sprintf( ' ' . __('Required fields are marked %s'), '<span class="required">*</span>' );
+
+    /**
+     * Filter the default comment form fields.
+     *
+     * @since 3.0.0
+     *
+     * @param array $fields The default comment fields.
+     */
+    $fields = apply_filters( 'comment_form_default_fields', $fields );
     $defaults = array(
-        'fields'               => apply_filters( 'comment_form_default_fields', $fields ),
+        'fields'               => $fields,
         '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>',
         '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>',
@@ -1712 +1949 @@
     );
 
+    /**
+     * Filter the comment form default arguments.
+     *
+     * Use 'comment_form_default_fields' to filter the comment fields.
+     *
+     * @since 3.0.0
+     *
+     * @param array $defaults The default comment form arguments.
+     */
     $args = wp_parse_args( $args, apply_filters( 'comment_form_defaults', $defaults ) );
 
     ?>
         <?php if ( comments_open( $post_id ) ) : ?>
-            <?php do_action( 'comment_form_before' ); ?>
+            <?php
+            /**
+             * Fires before the comment form.
+             *
+             * @since 3.0.0
+             */
+            do_action( 'comment_form_before' );
+            ?>
             <div id="respond" class="comment-respond">
                 <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>
                 <?php if ( get_option( 'comment_registration' ) && !is_user_logged_in() ) : ?>
                     <?php echo $args['must_log_in']; ?>
-                    <?php do_action( 'comment_form_must_log_in_after' ); ?>
+                    <?php
+                    /**
+                     * Fires after the HTML-formatted 'must log in after' message in the comment form.
+                     *
+                     * @since 3.0.0
+                     */
+                    do_action( 'comment_form_must_log_in_after' );
+                    ?>
                 <?php else : ?>
                     <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' : ''; ?>>
-                        <?php do_action( 'comment_form_top' ); ?>
+                        <?php
+                        /**
+                         * Fires at the top of the comment form, inside the <form> tag.
+                         *
+                         * @since 3.0.0
+                         */
+                        do_action( 'comment_form_top' );
+                        ?>
                         <?php if ( is_user_logged_in() ) : ?>
-                            <?php echo apply_filters( 'comment_form_logged_in', $args['logged_in_as'], $commenter, $user_identity ); ?>
-                            <?php do_action( 'comment_form_logged_in_after', $commenter, $user_identity ); ?>
+                            <?php
+                            /**
+                             * Filter the 'logged in' message for the comment form for display.
+                             *
+                             * @since 3.0.0
+                             *
+                             * @param string $args['logged_in_as'] The logged-in-as HTML-formatted message.
+                             * @param array  $commenter            An array containing the comment author's username, email, and URL.
+                             * @param string $user_identity        If the commenter is a registered user, the display name, blank otherwise.
+                             */
+                            echo apply_filters( 'comment_form_logged_in', $args['logged_in_as'], $commenter, $user_identity );
+                            ?>
+                            <?php
+                            /**
+                             * Fires after the is_user_logged_in() check in the comment form.
+                             *
+                             * @since 3.0.0
+                             *
+                             * @param array  $commenter     An array containing the comment author's username, email, and URL.
+                             * @param string $user_identity If the commenter is a registered user, the display name, blank otherwise.
+                             */
+                            do_action( 'comment_form_logged_in_after', $commenter, $user_identity );
+                            ?>
                         <?php else : ?>
                             <?php echo $args['comment_notes_before']; ?>
                             <?php
+                            /**
+                             * Fires before the comment fields in the comment form.
+                             *
+                             * @since 3.0.0
+                             */
                             do_action( 'comment_form_before_fields' );
                             foreach ( (array) $args['fields'] as $name => $field ) {
+                                /**
+                                 * Filter a comment form field for display.
+                                 *
+                                 * The dynamic portion of the filter hook, $name, refers to the name
+                                 * of the comment form field. Such as 'author', 'email', or 'url'.
+                                 *
+                                 * @since 3.0.0
+                                 *
+                                 * @param string $field The HTML-formatted output of the comment form field.
+                                 */
                                 echo apply_filters( "comment_form_field_{$name}", $field ) . "\n";
                             }
+                            /**
+                             * Fires after the comment fields in the comment form.
+                             *
+                             * @since 3.0.0
+                             */
                             do_action( 'comment_form_after_fields' );
                             ?>
                         <?php endif; ?>
-                        <?php echo apply_filters( 'comment_form_field_comment', $args['comment_field'] ); ?>
+                        <?php
+                        /**
+                         * Filter the content of the comment textarea field for display.
+                         *
+                         * @since 3.0.0
+                         *
+                         * @param string $args['comment_field'] The content of the comment textarea field.
+                         */
+                        echo apply_filters( 'comment_form_field_comment', $args['comment_field'] );
+                        ?>
                         <?php echo $args['comment_notes_after']; ?>
                         <p class="form-submit">
@@ -1744 +2061 @@
                             <?php comment_id_fields( $post_id ); ?>
                         </p>
-                        <?php do_action( 'comment_form', $post_id ); ?>
+                        <?php
+                        /**
+                         * Fires at the bottom of the comment form, inside the closing </form> tag.
+                         *
+                         * @since 1.5.2
+                         *
+                         * @param int $post_id The post ID.
+                         */
+                        do_action( 'comment_form', $post_id );
+                        ?>
                     </form>
                 <?php endif; ?>
             </div><!-- #respond -->
-            <?php do_action( 'comment_form_after' ); ?>
-        <?php else : ?>
-            <?php do_action( 'comment_form_comments_closed' ); ?>
-        <?php endif; ?>
-    <?php
-}
+            <?php
+            /**
+             * Fires after the comment form.
+             *
+             * @since 3.0.0
+             */
+            do_action( 'comment_form_after' );
+        else :
+            /**
+             * Fires after the comment form if comments are closed.
+             *
+             * @since 3.0.0
+             */
+            do_action( 'comment_form_comments_closed' );
+        endif;
+}