Changeset 25428

Timestamp:

09/13/2013 07:19:45 PM (12 years ago)

Author:

SergeyBiryukov

Message:

Inline documentation for get_comment_reply_link() and 'comment_reply_link' filter.

props DrewAPicture.
fixes #25310.

File:

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

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

@@ -1019 +1019 @@
  * Retrieve HTML content for reply to comment link.
  *
+ * @since 2.7.0
+ *
+ * @param array $args {
+ *     Override default options.
+ *
+ *     @type string 'add_below'  The first part of the selector used to identify the comment to respond below. The resulting value is passed as the first parameter to addComment.moveForm(), concatenated as $add_below-$comment->comment_ID.
+ *                               Default is 'comment'.
+ *     @type string 'respond_id' The selector identifying the responding comment. Passed as the third parameter to addComment.moveForm(), and appended to the link URL as a hash value.
+ *                               Default is 'respond'.
+ *     @type string 'reply_text' The text of the Reply link.
+ *                               Default is 'Reply'.
+ *     @type string 'login_text' The text of the link to reply if logged out.
+ *                               Default is 'Log in to Reply'.
+ *     @type int    'depth'      The depth of the new comment. Must be greater than 0 and less than the value of the 'thread_comments_depth' option set in Settings > Discussion.
+ *                               Default is 0.
+ *     @type string 'before'     The text or HTML to add before the reply link.
+ *                               Default empty string.
+ *     @type string 'after'      The text or HTML to add after the reply link.
+ *                               Default empty string.
+ * }
+ * @param int $comment Optional. Comment being replied to.
+ * @param int $post    Optional. Post that the comment is going to be displayed on.
+ * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
+ */
+function get_comment_reply_link($args = array(), $comment = null, $post = null) {
+    global $user_ID;
+
+    $defaults = array(
+        'add_below'  => 'comment',
+        'respond_id' => 'respond',
+        'reply_text' => __('Reply'),
+        'login_text' => __('Log in to Reply'),
+        'depth'      => 0,
+        'before'     => '',
+        'after'      => ''
+    );
+
+    $args = wp_parse_args($args, $defaults);
+
+    if ( 0 == $args['depth'] || $args['max_depth'] <= $args['depth'] )
+        return;
+
+    extract($args, EXTR_SKIP);
+
+    $comment = get_comment($comment);
+    if ( empty($post) )
+        $post = $comment->comment_post_ID;
+    $post = get_post($post);
+
+    if ( !comments_open($post->ID) )
+        return false;
+
+    $link = '';
+
+    if ( get_option('comment_registration') && !$user_ID )
+        $link = '<a rel="nofollow" class="comment-reply-login" href="' . esc_url( wp_login_url( get_permalink() ) ) . '">' . $login_text . '</a>';
+    else
+        $link = "<a class='comment-reply-link' href='" . esc_url( add_query_arg( 'replytocom', $comment->comment_ID ) ) . "#" . $respond_id . "' onclick='return addComment.moveForm(\"$add_below-$comment->comment_ID\", \"$comment->comment_ID\", \"$respond_id\", \"$post->ID\")'>$reply_text</a>";
+
+    /**
+     * Filter the comment reply link.
+     *
+     * @since 2.7.0
+     *
+     * @param string  $before  Text or HTML displayed before the reply link.
+     * @param string  $link    The HTML markup for the comment reply link.
+     * @param string  $after   Text or HTML displayed after the reply link.
+     * @param array   $args    An array of arguments overriding the defaults.
+     * @param object  $comment The object of the comment being replied.
+     * @param WP_Post $post    The WP_Post object.
+     */
+    return apply_filters( 'comment_reply_link', $before . $link . $after, $args, $comment, $post );
+}
+
+/**
+ * Displays the HTML content for reply to comment link.
+ *
+ * @since 2.7.0
+ * @see get_comment_reply_link() Echoes result
+ *
+ * @param array $args Optional. Override default options, @see get_comment_reply_link().
+ * @param int $comment Optional. Comment being replied to.
+ * @param int $post Optional. Post that the comment is going to be displayed on.
+ * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
+ */
+function comment_reply_link($args = array(), $comment = null, $post = null) {
+    echo get_comment_reply_link($args, $comment, $post);
+}
+
+/**
+ * Retrieve HTML content for reply to post link.
+ *
  * The default arguments that can be override are 'add_below', 'respond_id',
  * 'reply_text', 'login_text', and 'depth'. The 'login_text' argument will be
@@ -1026 +1118 @@
  * parameters.
  *
- * @since 2.7.0
- *
- * @param array $args Optional. Override default options.
- * @param int $comment Optional. Comment being replied to.
- * @param int $post Optional. Post that the comment is going to be displayed on.
- * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
- */
-function get_comment_reply_link($args = array(), $comment = null, $post = null) {
-    global $user_ID;
-
-    $defaults = array('add_below' => 'comment', 'respond_id' => 'respond', 'reply_text' => __('Reply'),
-        'login_text' => __('Log in to Reply'), 'depth' => 0, 'before' => '', 'after' => '');
-
-    $args = wp_parse_args($args, $defaults);
-
-    if ( 0 == $args['depth'] || $args['max_depth'] <= $args['depth'] )
-        return;
-
-    extract($args, EXTR_SKIP);
-
-    $comment = get_comment($comment);
-    if ( empty($post) )
-        $post = $comment->comment_post_ID;
-    $post = get_post($post);
-
-    if ( !comments_open($post->ID) )
-        return false;
-
-    $link = '';
-
-    if ( get_option('comment_registration') && !$user_ID )
-        $link = '<a rel="nofollow" class="comment-reply-login" href="' . esc_url( wp_login_url( get_permalink() ) ) . '">' . $login_text . '</a>';
-    else
-        $link = "<a class='comment-reply-link' href='" . esc_url( add_query_arg( 'replytocom', $comment->comment_ID ) ) . "#" . $respond_id . "' onclick='return addComment.moveForm(\"$add_below-$comment->comment_ID\", \"$comment->comment_ID\", \"$respond_id\", \"$post->ID\")'>$reply_text</a>";
-    return apply_filters('comment_reply_link', $before . $link . $after, $args, $comment, $post);
-}
-
-/**
- * Displays the HTML content for reply to comment link.
- *
- * @since 2.7.0
- * @see get_comment_reply_link() Echoes result
- *
- * @param array $args Optional. Override default options.
- * @param int $comment Optional. Comment being replied to.
- * @param int $post Optional. Post that the comment is going to be displayed on.
- * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
- */
-function comment_reply_link($args = array(), $comment = null, $post = null) {
-    echo get_comment_reply_link($args, $comment, $post);
-}
-
-/**
- * Retrieve HTML content for reply to post link.
- *
- * The default arguments that can be override are 'add_below', 'respond_id',
- * 'reply_text', 'login_text', and 'depth'. The 'login_text' argument will be
- * used, if the user must log in or register first before posting a comment. The
- * 'reply_text' will be used, if they can post a reply. The 'add_below' and
- * 'respond_id' arguments are for the JavaScript moveAddCommentForm() function
- * parameters.
+ * @todo See get_comment_reply_link() for a template of the args docblock.
  *
  * @since 2.7.0
@@ -1117 +1149 @@
 /**
  * Displays the HTML content for reply to post link.
+ * 
  * @since 2.7.0
- * @see get_post_reply_link()
- *
- * @param array $args Optional. Override default options.
+ *
+ * @param array $args Optional. Override default options, @see get_post_reply_link().
  * @param int|object $post Optional. Post that the comment is going to be displayed on.
  * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.