From 369317d2a7f8333be312743c31034b744c36fcbe Mon Sep 17 00:00:00 2001 From: ryan Date: Wed, 24 Sep 2008 20:02:41 +0000 Subject: [PATCH] phpdoc for comments-template from jacobsantos. see #7550 git-svn-id: http://svn.automattic.com/wordpress/trunk@8970 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/comment-template.php | 127 +++++++++++++++++++++++++------ 1 file changed, 103 insertions(+), 24 deletions(-) diff --git a/wp-includes/comment-template.php b/wp-includes/comment-template.php index 4f53d9a309..c655412006 100644 --- a/wp-includes/comment-template.php +++ b/wp-includes/comment-template.php @@ -14,7 +14,7 @@ * If the comment has an empty comment_author field, then 'Anonymous' person is * assumed. * - * @since 1.5 + * @since 1.5.0 * @uses apply_filters() Calls 'get_comment_author' hook on the comment author * * @return string The comment author @@ -42,7 +42,7 @@ function comment_author() { /** * Retrieve the email of the author of the current comment. * - * @since 1.5 + * @since 1.5.0 * @uses apply_filters() Calls the 'get_comment_author_email' hook on the comment author email * @uses $comment * @@ -100,7 +100,7 @@ function comment_author_email_link($linktext='', $before='', $after='') { /** * Retrieve the html link to the url of the author of the current comment. * - * @since 1.5 + * @since 1.5.0 * @uses apply_filters() Calls 'get_comment_author_link' hook on the complete link HTML or author * * @return string Comment Author name or HTML link for author's URL @@ -130,7 +130,7 @@ function comment_author_link() { /** * Retrieve the IP address of the author of the current comment. * - * @since 1.5 + * @since 1.5.0 * @uses $comment * @uses apply_filters() * @@ -154,7 +154,7 @@ function comment_author_IP() { /** * Retrieve the url of the author of the current comment. * - * @since 1.5 + * @since 1.5.0 * @uses apply_filters() Calls 'get_comment_author_url' hook on the comment author's URL * * @return string @@ -185,7 +185,7 @@ function comment_author_url() { * Encapsulate the HTML link between the $before and $after. So it will appear * in the order of $before, link, and finally $after. * - * @since 1.5 + * @since 1.5.0 * @uses apply_filters() Calls the 'get_comment_author_url_link' on the complete HTML before returning. * * @param string $linktext The text to display instead of the comment author's email address @@ -221,7 +221,7 @@ function comment_author_url_link( $linktext = '', $before = '', $after = '' ) { /** * Generates semantic classes for each comment element * - * @since 2.7 + * @since 2.7.0 * * @param string|array $class One or more classes to add to the class list * @param int $comment_id An optional comment ID @@ -239,7 +239,7 @@ function comment_class( $class = '', $comment_id = null, $post_id = null, $echo /** * Returns the classes for the comment div as an array * - * @since 2.7 + * @since 2.7.0 * * @param string|array $class One or more classes to add to the class list * @param int $comment_id An optional comment ID @@ -308,7 +308,7 @@ function get_comment_class( $class = '', $comment_id = null, $post_id = null ) { /** * Retrieve the comment date of the current comment. * - * @since 1.5 + * @since 1.5.0 * @uses apply_filters() Calls 'get_comment_date' hook with the formated date and the $d parameter respectively * @uses $comment * @@ -342,7 +342,7 @@ function comment_date( $d = '' ) { * If the word count is less than 20, then no truncating is done and no '...' * will appear. * - * @since 1.5 + * @since 1.5.0 * @uses $comment * @uses apply_filters() Calls 'get_comment_excerpt' on truncated comment * @@ -370,7 +370,7 @@ function get_comment_excerpt() { /** * Display the excerpt of the current comment. * - * @since 1.2 + * @since 1.2.0 * @uses apply_filters() Calls 'comment_excerpt' hook before displaying excerpt */ function comment_excerpt() { @@ -380,7 +380,7 @@ function comment_excerpt() { /** * Retrieve the comment id of the current comment. * - * @since 1.5 + * @since 1.5.0 * @uses $comment * @uses apply_filters() Calls the 'get_comment_ID' hook for the comment ID * @@ -404,7 +404,7 @@ function comment_ID() { /** * Retrieve the link to the current comment. * - * @since 1.5 + * @since 1.5.0 * @uses $comment * * @param object|string|int $comment Comment to retrieve. @@ -418,7 +418,7 @@ function get_comment_link($comment = null) { /** * Retrieves the link to the current post comments. * - * @since 1.5 + * @since 1.5.0 * * @return string The link to the comments */ @@ -441,7 +441,7 @@ function comments_link( $deprecated = '', $deprecated = '' ) { /** * Retrieve the amount of comments a post has. * - * @since 1.5 + * @since 1.5.0 * @uses apply_filters() Calls the 'get_comments_number' hook on the number of comments * * @param int $post_id The Post ID @@ -492,7 +492,7 @@ function comments_number( $zero = false, $one = false, $more = false, $deprecate /** * Retrieve the text of the current comment. * - * @since 1.5 + * @since 1.5.0 * @uses $comment * * @return string The comment content @@ -516,7 +516,7 @@ function comment_text() { /** * Retrieve the comment time of the current comment. * - * @since 1.5 + * @since 1.5.0 * @uses $comment * @uses apply_filter() Calls 'get_comment_time' hook with the formatted time, the $d parameter, and $gmt parameter passed. * @@ -548,7 +548,7 @@ function comment_time( $d = '' ) { /** * Retrieve the comment type of the current comment. * - * @since 1.5 + * @since 1.5.0 * @uses $comment * @uses apply_filters() Calls the 'get_comment_type' hook on the comment type * @@ -593,7 +593,7 @@ function comment_type($commenttxt = 'Comment', $trackbacktxt = 'Trackback', $pin * retrieve the pretty path. If permalinks weren't enabled, the ID of the * current post is used and appended to the correct page to go to. * - * @since 1.5 + * @since 1.5.0 * @uses apply_filters() Calls 'trackback_url' on the resulting trackback URL * @uses $id * @@ -650,7 +650,7 @@ function trackback_rdf($deprecated = '') { /** * Whether the current post is open for comments. * - * @since 1.5 + * @since 1.5.0 * @uses $post * * @param int $post_id An optional post ID to check instead of the current post. @@ -667,7 +667,7 @@ function comments_open( $post_id=NULL ) { /** * Whether the current post is open for pings. * - * @since 1.5 + * @since 1.5.0 * @uses $post * * @param int $post_id An optional post ID to check instead of the current post. @@ -691,7 +691,8 @@ function pings_open( $post_id = NULL ) { * above. Does not exist in versions prior to 2.0.10 in the 2.0 branch and in * the 2.1 branch, prior to 2.1.3. Technically added in 2.2.0. * - * @since 2.0.10 Backported to 2.0 branch + * Backported to 2.0.10. + * * @since 2.1.3 * @uses $post Gets the ID of the current post for the token */ @@ -717,7 +718,7 @@ function wp_comment_form_unfiltered_html_nonce() { * default theme. If either does not exist, then the WordPress process will be * halted. It is advised for that reason, that the default theme is not deleted. * - * @since 1.5 + * @since 1.5.0 * @global array $comment List of comment objects for the current post * @uses $wpdb * @uses $id @@ -859,6 +860,23 @@ function comments_popup_link( $zero = 'No Comments', $one = '1 Comment', $more = echo ''; } +/** + * Retrieve HTML content for reply to comment 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. + * + * @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 comment_reply_link($args = array(), $comment = null, $post = null) { global $user_ID; @@ -888,16 +906,51 @@ function comment_reply_link($args = array(), $comment = null, $post = null) { return $link; } +/** + * Display HTML content for cancel comment reply link. + * + * @since 2.7.0 + * + * @param string $text Optional. Text to display for cancel reply. + * @param string $respond_id Optional. HTML ID attribute for JS cancelCommentReply function. + * @param string $respond_root Optional. Second parameter for JS cancelCommentReply function. + */ function cancel_comment_reply_link($text = '', $respond_id = 'respond', $respond_root = 'content') { if ( empty($text) ) $text = __('Click here to cancel reply.'); echo '' . $text . ''; } +/** + * HTML comment list class. + * + * @package WordPress + * @uses Walker + * @since unknown + */ class Walker_Comment extends Walker { + /** + * @see Walker::$tree_type + * @since unknown + * @var string + */ var $tree_type = 'comment'; + + /** + * @see Walker::$db_fields + * @since unknown + * @var array + */ var $db_fields = array ('parent' => 'comment_parent', 'id' => 'comment_ID'); + /** + * @see Walker::start_lvl() + * @since unknown + * + * @param string $output Passed by reference. Used to append additional content. + * @param int $depth Depth of comment. + * @param array $args Uses 'style' argument for type of HTML list. + */ function start_lvl(&$output, $depth, $args) { $GLOBALS['comment_depth'] = $depth + 1; @@ -914,6 +967,14 @@ class Walker_Comment extends Walker { } } + /** + * @see Walker::end_lvl() + * @since unknown + * + * @param string $output Passed by reference. Used to append additional content. + * @param int $depth Depth of comment. + * @param array $args Will only append content if style argument value is 'ol' or 'ul'. + */ function end_lvl(&$output, $depth, $args) { $GLOBALS['comment_depth'] = $depth + 1; @@ -930,6 +991,15 @@ class Walker_Comment extends Walker { } } + /** + * @see Walker::start_el() + * @since unknown + * + * @param string $output Passed by reference. Used to append additional content. + * @param object $comment Comment data object. + * @param int $depth Depth of comment in reference to parents. + * @param array $args + */ function start_el(&$output, $comment, $depth, $args) { $depth++; $GLOBALS['comment_depth'] = $depth; @@ -976,6 +1046,15 @@ class Walker_Comment extends Walker {