<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"

"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />

<title>[25567] trunk/src/wp-includes/comment-template.php: Inline documentation improvements for wp-includes/comment-template.php.</title>

</head>

<body>

<style type="text/css"><!--

#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }

#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }

#msg dt:after { content:':';}

#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt;  }

#msg dl a { font-weight: bold}

#msg dl a:link    { color:#fc3; }

#msg dl a:active  { color:#ff0; }

#msg dl a:visited { color:#cc6; }

h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }

#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }

#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }

#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }

#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }

#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }

#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }

#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }

#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }

#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }

#logmsg pre { background: #eee; padding: 1em; }

#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}

#logmsg dl { margin: 0; }

#logmsg dt { font-weight: bold; }

#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }

#logmsg dd:before { content:'\00bb';}

#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }

#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }

#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }

#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }

#logmsg table th.Corner { text-align: left; }

#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }

#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }

#patch { width: 100%; }

#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}

#patch .propset h4, #patch .binary h4 {margin:0;}

#patch pre {padding:0;line-height:1.2em;margin:0;}

#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}

#patch .propset .diff, #patch .binary .diff  {padding:10px 0;}

#patch span {display:block;padding:0 10px;}

#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}

#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}

#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}

#patch .lines, .info {color:#888;background:#fff;}

--></style>

<div id="msg">

<dl class="meta">

<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/25567">25567</a></dd>

<dt>Author</dt> <dd>DrewAPicture</dd>

<dt>Date</dt> <dd>2013-09-23 04:15:41 +0000 (Mon, 23 Sep 2013)</dd>

</dl>

<h3>Log Message</h3>

<pre>Inline documentation improvements for wp-includes/comment-template.php.

Changes include:

- Existing phpdoc block improvements

- Inclusion of defaults for optional parameters

- Hash-notated argument arrays

- Removal of unnecessary or redundant tagging.

Also standardization of int|WP_Post function parameters.

These changes clear the way toward less redundancy for hook docs in a future ticket.

Still left: Fully documented arguments in `comment_form()` and a pass through Walker_Comment.

See <a href="http://core.trac.wordpress.org/ticket/20495">#20495</a>. See <a href="http://core.trac.wordpress.org/ticket/25388">#25388</a>.</pre>

<h3>Modified Paths</h3>

<ul>

<li><a href="#trunksrcwpincludescommenttemplatephp">trunk/src/wp-includes/comment-template.php</a></li>

</ul>

</div>

<div id="patch">

<h3>Diff</h3>

<a id="trunksrcwpincludescommenttemplatephp"></a>

<div class="modfile"><h4>Modified: trunk/src/wp-includes/comment-template.php (25566 => 25567)</h4>

<pre class="diff"><span>

<span class="info">--- trunk/src/wp-includes/comment-template.php       2013-09-23 02:07:51 UTC (rev 25566)

+++ trunk/src/wp-includes/comment-template.php  2013-09-23 04:15:41 UTC (rev 25567)

</span><span class="lines">@@ -15,9 +15,8 @@

<span class="cx">  * assumed.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses apply_filters() Calls 'get_comment_author' hook on the comment author

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to retrieve the author. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to retrieve the author. Default current comment.

</ins><span class="cx">  * @return string The comment author

</span><span class="cx">  */

</span><span class="cx"> function get_comment_author( $comment_ID = 0 ) {

</span><span class="lines">@@ -39,9 +38,8 @@

<span class="cx">  * Displays the author of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><del>- * @uses apply_filters() Calls 'comment_author' on comment author before displaying

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to print the author. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to print the author. Default current comment.

</ins><span class="cx">  */

</span><span class="cx"> function comment_author( $comment_ID = 0 ) {

</span><span class="cx">  $author = apply_filters('comment_author', get_comment_author( $comment_ID ) );

</span><span class="lines">@@ -52,10 +50,8 @@

<span class="cx">  * Retrieve the email of the author of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses apply_filters() Calls the 'get_comment_author_email' hook on the comment author email

- * @uses $comment

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to get the author's email. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to get the author's email. Default current comment.

</ins><span class="cx">  * @return string The current comment author's email

</span><span class="cx">  */

</span><span class="cx"> function get_comment_author_email( $comment_ID = 0 ) {

</span><span class="lines">@@ -73,9 +69,8 @@

<span class="cx">  * address and use it for their own means good and bad.

</span><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><del>- * @uses apply_filters() Calls 'author_email' hook on the author email

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to print the author's email. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to print the author's email. Default current comment.

</ins><span class="cx">  */

</span><span class="cx"> function comment_author_email( $comment_ID = 0 ) {

</span><span class="cx">  echo apply_filters('author_email', get_comment_author_email( $comment_ID ) );

</span><span class="lines">@@ -90,16 +85,15 @@

</span><span class="cx">  * enable anyone, including those that people don't want to get the email

<span class="cx">  * address and use it for their own means good and bad.

</span><span class="cx">  *

</span><ins>+ * @global object $comment The current Comment row object

+

</ins><span class="cx">  * @since 0.71

</span><del>- * @uses apply_filters() Calls 'comment_email' hook for the display of the comment author's email

- * @uses get_comment_author_email_link() For generating the link

- * @global object $comment The current Comment row object

</del><span class="cx">  *

</span><del>- * @param string $linktext The text to display instead of the comment author's email address

- * @param string $before The text or HTML to display before the email link.

- * @param string $after The text or HTML to display after the email link.

</del><ins>+ * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.

+ * @param string $before   Optional. The text or HTML to display before the email link.Default empty.

+ * @param string $after    Optional. The text or HTML to display after the email link. Default empty.

</ins><span class="cx">  */

</span><del>-function comment_author_email_link($linktext='', $before='', $after='') {

</del><ins>+function comment_author_email_link( $linktext = '', $before = '', $after = '' ) {

</ins><span class="cx">   if ( $link = get_comment_author_email_link( $linktext, $before, $after ) )

</span><span class="cx">          echo $link;

</span><span class="cx"> }

</span><span class="lines">@@ -113,15 +107,15 @@

</span><span class="cx">  * enable anyone, including those that people don't want to get the email

<span class="cx">  * address and use it for their own means good and bad.

</span><span class="cx">  *

<ins>+ * @global object $comment The current Comment row object.

+ *

</ins><span class="cx">  * @since 2.7

</span><del>- * @uses apply_filters() Calls 'comment_email' hook for the display of the comment author's email

- * @global object $comment The current Comment row object

</del><span class="cx">  *

</span><del>- * @param string $linktext The text to display instead of the comment author's email address

- * @param string $before The text or HTML to display before the email link.

- * @param string $after The text or HTML to display after the email link.

</del><ins>+ * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.

+ * @param string $before   Optional. The text or HTML to display before the email link. Default empty.

+ * @param string $after    Optional. The text or HTML to display after the email link. Default empty.

</ins><span class="cx">  */

</span><del>-function get_comment_author_email_link($linktext='', $before='', $after='') {

</del><ins>+function get_comment_author_email_link( $linktext = '', $before = '', $after = '' ) {

</ins><span class="cx">   global $comment;

</span><span class="cx">  $email = apply_filters('comment_email', $comment->comment_author_email);

</span><span class="cx">  if ((!empty($email)) && ($email != '@')) {

</span><span class="lines">@@ -143,7 +137,7 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><span class="cx">  *

<del>- * @param int $comment_ID Optional. The ID of the comment for which to get the author's link.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to get the author's link. Default current comment.

</ins><span class="cx">  * @return string The comment author name or HTML link for author's URL.

</span><span class="cx">  */

</span><span class="cx"> function get_comment_author_link( $comment_ID = 0 ) {

</span><span class="lines">@@ -163,7 +157,7 @@

</span><span class="cx">  * @since 0.71

</span><span class="cx">  * @see get_comment_author_link() Echoes result

</span><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to print the author's link. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to print the author's link. Default current comment.

</ins><span class="cx">  */

</span><span class="cx"> function comment_author_link( $comment_ID = 0 ) {

</span><span class="cx">  echo get_comment_author_link( $comment_ID );

</span><span class="lines">@@ -173,10 +167,8 @@

<span class="cx">  * Retrieve the IP address of the author of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses $comment

- * @uses apply_filters()

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to get the author's IP address. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to get the author's IP address. Default current comment.

</ins><span class="cx">  * @return string The comment author's IP address.

</span><span class="cx">  */

</span><span class="cx"> function get_comment_author_IP( $comment_ID = 0 ) {

</span><span class="lines">@@ -188,9 +180,8 @@

<span class="cx">  * Display the IP address of the author of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><del>- * @see get_comment_author_IP() Echoes Result

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to print the author's IP address. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to print the author's IP address. Default current comment.

</ins><span class="cx">  */

</span><span class="cx"> function comment_author_IP( $comment_ID = 0 ) {

</span><span class="cx">  echo get_comment_author_IP( $comment_ID );

</span><span class="lines">@@ -200,9 +191,8 @@

<span class="cx">  * Retrieve the url of the author of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses apply_filters() Calls 'get_comment_author_url' hook on the comment author's URL

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to get the author's URL. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to get the author's URL. Default current comment.

</ins><span class="cx">  * @return string

</span><span class="cx">  */

</span><span class="cx"> function get_comment_author_url( $comment_ID = 0 ) {

</span><span class="lines">@@ -216,10 +206,8 @@

<span class="cx">  * Display the url of the author of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><del>- * @uses apply_filters()

- * @uses get_comment_author_url() Retrieves the comment author's URL

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to print the author's URL. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to print the author's URL. Default current comment.

</ins><span class="cx">  */

</span><span class="cx"> function comment_author_url( $comment_ID = 0 ) {

</span><span class="cx">  echo apply_filters('comment_url', get_comment_author_url( $comment_ID ));

</span><span class="lines">@@ -236,12 +224,11 @@

<span class="cx">  * in the order of $before, link, and finally $after.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

<del>- * @uses apply_filters() Calls the 'get_comment_author_url_link' on the complete HTML before returning.

</del><span class="cx">  *

</span><del>- * @param string $linktext The text to display instead of the comment author's email address

- * @param string $before The text or HTML to display before the email link.

- * @param string $after The text or HTML to display after the email link.

- * @return string The HTML link between the $before and $after parameters

</del><ins>+ * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.

+ * @param string $before   Optional. The text or HTML to display before the email link. Default empty.

+ * @param string $after    Optional. The text or HTML to display after the email link. Default empty.

+ * @return string The HTML link between the $before and $after parameters.

</ins><span class="cx">  */

</span><span class="cx"> function get_comment_author_url_link( $linktext = '', $before = '', $after = '' ) {

</span><span class="cx">  $url = get_comment_author_url();

</span><span class="lines">@@ -258,11 +245,10 @@

<span class="cx">  * Displays the HTML link of the url of the author of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><del>- * @see get_comment_author_url_link() Echoes result

</del><span class="cx">  *

</span><del>- * @param string $linktext The text to display instead of the comment author's email address

- * @param string $before The text or HTML to display before the email link.

- * @param string $after The text or HTML to display after the email link.

</del><ins>+ * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.

+ * @param string $before   Optional. The text or HTML to display before the email link. Default empty.

+ * @param string $after    Optional. The text or HTML to display after the email link. Default empty.

</ins><span class="cx">  */

</span><span class="cx"> function comment_author_url_link( $linktext = '', $before = '', $after = '' ) {

</span><span class="cx">  echo get_comment_author_url_link( $linktext, $before, $after );

</span><span class="lines">@@ -273,10 +259,10 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 2.7.0

</span><span class="cx">  *

</span><del>- * @param string|array $class One or more classes to add to the class list

- * @param int $comment_id An optional comment ID

- * @param int $post_id An optional post ID

- * @param bool $echo Whether comment_class should echo or return

</del><ins>+ * @param string|array $class      Optional. One or more classes to add to the class list. Default empty.

+ * @param int          $comment_id Optional. Comment ID. Default current comment.

+ * @param int|WP_Post  $post_id    Optional. Post ID or WP_Post object. Default current post.

+ * @param bool         $echo       Optional. Whether comment_class should echo or return. Default true.

</ins><span class="cx">  */

</span><span class="cx"> function comment_class( $class = '', $comment_id = null, $post_id = null, $echo = true ) {

</span><span class="cx">  // Separates classes with a single space, collates classes for comment DIV

</span><span class="lines">@@ -292,10 +278,10 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 2.7.0

</span><span class="cx">  *

</span><del>- * @param string|array $class One or more classes to add to the class list

- * @param int $comment_id An optional comment ID

- * @param int $post_id An optional post ID

- * @return array Array of classes

</del><ins>+ * @param string|array $class      Optional. One or more classes to add to the class list. Default empty.

+ * @param int          $comment_id Optional. Comment ID. Default current comment.

+ * @param int|WP_Post  $post_id    Optional. Post ID or WP_Post object. Default current post.

+ * @return array An array of classes.

</ins><span class="cx">  */

</span><span class="cx"> function get_comment_class( $class = '', $comment_id = null, $post_id = null ) {

</span><span class="cx">  global $comment_alt, $comment_depth, $comment_thread_alt;

</span><span class="lines">@@ -363,12 +349,10 @@

<span class="cx">  * Retrieve the comment date of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses apply_filters() Calls 'get_comment_date' hook with the formatted date and the $d parameter respectively

- * @uses $comment

</del><span class="cx">  *

</span><del>- * @param string $d The format of the date (defaults to user's config)

- * @param int $comment_ID The ID of the comment for which to get the date. Optional.

- * @return string The comment's date

</del><ins>+ * @param string $d          Optional. The format of the date. Default user's setting.

+ * @param int    $comment_ID Optional. The ID of the comment for which to get the date. Default current comment.

+ * @return string The comment's date.

</ins><span class="cx">  */

</span><span class="cx"> function get_comment_date( $d = '', $comment_ID = 0 ) {

</span><span class="cx">  $comment = get_comment( $comment_ID );

</span><span class="lines">@@ -384,8 +368,8 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><span class="cx">  *

</span><del>- * @param string $d The format of the date (defaults to user's config)

- * @param int $comment_ID The ID of the comment for which to print the date. Optional.

</del><ins>+ * @param string $d          Optional. The format of the date. Default user's settings.

+ * @param int    $comment_ID Optional. The ID of the comment for which to print the date. Default current comment.

</ins><span class="cx">  */

</span><span class="cx"> function comment_date( $d = '', $comment_ID = 0 ) {

</span><span class="cx">  echo get_comment_date( $d, $comment_ID );

</span><span class="lines">@@ -399,11 +383,9 @@

<span class="cx">  * will appear.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses $comment

- * @uses apply_filters() Calls 'get_comment_excerpt' on truncated comment

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to get the excerpt. Optional.

- * @return string The maybe truncated comment with 20 words or less

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to get the excerpt. Default current comment.

+ * @return string The maybe truncated comment with 20 words or less.

</ins><span class="cx">  */

</span><span class="cx"> function get_comment_excerpt( $comment_ID = 0 ) {

</span><span class="cx">  $comment = get_comment( $comment_ID );

</span><span class="lines">@@ -428,9 +410,8 @@

<span class="cx">  * Display the excerpt of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.2.0

</span><del>- * @uses apply_filters() Calls 'comment_excerpt' hook before displaying excerpt

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to print the excerpt. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to print the excerpt. Default current comment.

</ins><span class="cx">  */

</span><span class="cx"> function comment_excerpt( $comment_ID = 0 ) {

</span><span class="cx">  echo apply_filters('comment_excerpt', get_comment_excerpt($comment_ID) );

</span><span class="lines">@@ -440,10 +421,8 @@

<span class="cx">  * Retrieve the comment id of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses $comment

- * @uses apply_filters() Calls the 'get_comment_ID' hook for the comment ID

</del><span class="cx">  *

</span><del>- * @return int The comment ID

</del><ins>+ * @return int The comment ID.

</ins><span class="cx">  */

</span><span class="cx"> function get_comment_ID() {

</span><span class="cx">  global $comment;

</span><span class="lines">@@ -451,10 +430,9 @@

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

<del>- * Displays the comment id of the current comment.

</del><ins>+ * Display the comment id of the current comment.

</ins><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><del>- * @see get_comment_ID() Echoes Result

</del><span class="cx">  */

</span><span class="cx"> function comment_ID() {

</span><span class="cx">  echo get_comment_ID();

</span><span class="lines">@@ -464,10 +442,9 @@

<span class="cx">  * Retrieve the link to a given comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses $comment

</del><span class="cx">  *

<del>- * @param object|string|int $comment Comment to retrieve.

- * @param array $args Optional args.

</del><ins>+ * @param mixed $comment Optional. Comment to retrieve. Default current comment.

+ * @param array $args    Optional. An array of arguments to override the defaults. @see get_page_of_comment()

</ins><span class="cx">  * @return string The permalink to the given comment.

</span><span class="cx">  */

</span><span class="cx"> function get_comment_link( $comment = null, $args = array() ) {

</span><span class="lines">@@ -509,24 +486,24 @@

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

<del>- * Retrieves the link to the current post comments.

</del><ins>+ * Retrieve the link to the current post comments.

</ins><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><span class="cx">  *

</span><del>- * @param int $post_id Optional post id

- * @return string The link to the comments

</del><ins>+ * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.

+ * @return string The link to the comments.

</ins><span class="cx">  */

</span><del>-function get_comments_link($post_id = 0) {

</del><ins>+function get_comments_link( $post_id = 0 ) {

</ins><span class="cx">   return apply_filters( 'get_comments_link', get_permalink( $post_id ) . '#comments', $post_id );

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

<del>- * Displays the link to the current post comments.

</del><ins>+ * Display the link to the current post comments.

</ins><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><span class="cx">  *

</span><del>- * @param string $deprecated Not Used

- * @param bool $deprecated_2 Not Used

</del><ins>+ * @param string $deprecated   Not Used.

+ * @param bool   $deprecated_2 Not Used.

</ins><span class="cx">  */

</span><span class="cx"> function comments_link( $deprecated = '', $deprecated_2 = '' ) {

</span><span class="cx">  if ( !empty( $deprecated ) )

</span><span class="lines">@@ -540,10 +517,9 @@

<span class="cx">  * Retrieve the amount of comments a post has.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses apply_filters() Calls the 'get_comments_number' hook on the number of comments

</del><span class="cx">  *

</span><del>- * @param int $post_id The Post ID

- * @return int The number of comments a post has

</del><ins>+ * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.

+ * @return int The number of comments a post has.

</ins><span class="cx">  */

</span><span class="cx"> function get_comments_number( $post_id = 0 ) {

</span><span class="cx">  $post_id = absint( $post_id );

</span><span class="lines">@@ -564,11 +540,10 @@

<span class="cx">  * Display the language string for the number of comments the current post has.

</span><span class="cx">  *

</span><span class="cx">  * @since 0.71

<del>- * @uses apply_filters() Calls the 'comments_number' hook on the output and number of comments respectively.

</del><span class="cx">  *

</span><del>- * @param string $zero Text for no comments

- * @param string $one Text for one comment

- * @param string $more Text for more than one comment

</del><ins>+ * @param string $zero       Optional. Text for no comments. Default false.

+ * @param string $one        Optional. Text for one comment. Default false.

+ * @param string $more       Optional. Text for more than one comment. Default false.

</ins><span class="cx">  * @param string $deprecated Not used.

</span><span class="cx">  */

</span><span class="cx"> function comments_number( $zero = false, $one = false, $more = false, $deprecated = '' ) {

</span><span class="lines">@@ -592,10 +567,8 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><span class="cx">  *

<del>- * @param int   $comment_ID Optional. The ID of the comment for which to get the text.

- *                          Default 0.

</del><ins>+ * @param int   $comment_ID Optional. The ID of the comment for which to get the text. Default current comment.

</ins><span class="cx">  * @param array $args       Optional. An array of arguments. @see Walker_Comment::comment()

<del>- *                          Default empty array.

</del><span class="cx">  * @return string The comment content.

</span><span class="cx">  */

</span><span class="cx"> function get_comment_text( $comment_ID = 0, $args = array() ) {

</span><span class="lines">@@ -643,12 +616,10 @@

<span class="cx">  * Retrieve the comment time of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses $comment

- * @uses apply_filter() Calls 'get_comment_time' hook with the formatted time, the $d parameter, and $gmt parameter passed.

</del><span class="cx">  *

</span><del>- * @param string $d Optional. The format of the time (defaults to user's config)

- * @param bool $gmt Whether to use the GMT date

- * @param bool $translate Whether to translate the time (for use in feeds)

</del><ins>+ * @param string $d         Optional. The format of the time. Default user's settings.

+ * @param bool   $gmt       Optional. Whether to use the GMT date. Default false.

+ * @param bool   $translate Optional. Whether to translate the time (for use in feeds). Default true.

</ins><span class="cx">  * @return string The formatted time

</span><span class="cx">  */

</span><span class="cx"> function get_comment_time( $d = '', $gmt = false, $translate = true ) {

</span><span class="lines">@@ -666,7 +637,7 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><span class="cx">  *

</span><del>- * @param string $d Optional. The format of the time (defaults to user's config)

</del><ins>+ * @param string $d Optional. The format of the time. Default user's settings.

</ins><span class="cx">  */

</span><span class="cx"> function comment_time( $d = '' ) {

</span><span class="cx">  echo get_comment_time($d);

</span><span class="lines">@@ -676,10 +647,8 @@

<span class="cx">  * Retrieve the comment type of the current comment.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses $comment

- * @uses apply_filters() Calls the 'get_comment_type' hook on the comment type

</del><span class="cx">  *

<del>- * @param int $comment_ID The ID of the comment for which to get the type. Optional.

</del><ins>+ * @param int $comment_ID Optional. The ID of the comment for which to get the type. Default current comment.

</ins><span class="cx">  * @return string The comment type

</span><span class="cx">  */

</span><span class="cx"> function get_comment_type( $comment_ID = 0 ) {

</span><span class="lines">@@ -695,11 +664,11 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><span class="cx">  *

</span><del>- * @param string $commenttxt The string to display for comment type

- * @param string $trackbacktxt The string to display for trackback type

- * @param string $pingbacktxt The string to display for pingback type

</del><ins>+ * @param string $commenttxt   Optional. The string to display for comment type. Default false.

+ * @param string $trackbacktxt Optional. The string to display for trackback type. Default false.

+ * @param string $pingbacktxt  Optional. The string to display for pingback type. Default false.

</ins><span class="cx">  */

</span><del>-function comment_type($commenttxt = false, $trackbacktxt = false, $pingbacktxt = false) {

</del><ins>+function comment_type( $commenttxt = false, $trackbacktxt = false, $pingbacktxt = false ) {

</ins><span class="cx">   if ( false === $commenttxt ) $commenttxt = _x( 'Comment', 'noun' );

</span><span class="cx">  if ( false === $trackbacktxt ) $trackbacktxt = __( 'Trackback' );

</span><span class="cx">  if ( false === $pingbacktxt ) $pingbacktxt = __( 'Pingback' );

</span><span class="lines">@@ -724,9 +693,8 @@

<span class="cx">  * current post is used and appended to the correct page to go to.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses apply_filters() Calls 'trackback_url' on the resulting trackback URL

</del><span class="cx">  *

</span><del>- * @return string The trackback URL after being filtered

</del><ins>+ * @return string The trackback URL after being filtered.

</ins><span class="cx">  */

</span><span class="cx"> function get_trackback_url() {

</span><span class="cx">  if ( '' != get_option('permalink_structure') ) {

</span><span class="lines">@@ -738,12 +706,11 @@

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

<del>- * Displays the current post's trackback URL.

</del><ins>+ * Display the current post's trackback URL.

</ins><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><del>- * @uses get_trackback_url() Gets the trackback url for the current post

</del><span class="cx">  *

</span><del>- * @param bool $deprecated_echo Remove backwards compat in 2.5

</del><ins>+ * @param bool $deprecated_echo Not used.

</ins><span class="cx">  * @return void|string Should only be used to echo the trackback URL, use get_trackback_url() for the result instead.

</span><span class="cx">  */

</span><span class="cx"> function trackback_url( $deprecated_echo = true ) {

</span><span class="lines">@@ -756,13 +723,13 @@

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

<del>- * Generates and displays the RDF for the trackback information of current post.

</del><ins>+ * Generate and display the RDF for the trackback information of current post.

</ins><span class="cx">  *

<span class="cx">  * Deprecated in 3.0.0, and restored in 3.0.1.

</span><span class="cx">  *

</span><span class="cx">  * @since 0.71

</span><span class="cx">  *

</span><del>- * @param int $deprecated Not used (Was $timezone = 0)

</del><ins>+ * @param int $deprecated Not used (Was $timezone = 0).

</ins><span class="cx">  */

</span><span class="cx"> function trackback_rdf( $deprecated = '' ) {

</span><span class="cx">  if ( !empty( $deprecated ) )

</span><span class="lines">@@ -789,10 +756,9 @@

<span class="cx">  * Whether the current post is open for comments.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses $post

</del><span class="cx">  *

<del>- * @param int $post_id An optional post ID to check instead of the current post.

- * @return bool True if the comments are open

</del><ins>+ * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.

+ * @return bool True if the comments are open.

</ins><span class="cx">  */

</span><span class="cx"> function comments_open( $post_id = null ) {

</span><span class="cx"> 

</span><span class="lines">@@ -806,9 +772,8 @@

<span class="cx">  * Whether the current post is open for pings.

</span><span class="cx">  *

</span><span class="cx">  * @since 1.5.0

</span><del>- * @uses $post

</del><span class="cx">  *

<del>- * @param int $post_id An optional post ID to check instead of the current post.

</del><ins>+ * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.

</ins><span class="cx">  * @return bool True if pings are accepted

</span><span class="cx">  */

</span><span class="cx"> function pings_open( $post_id = null ) {

</span><span class="lines">@@ -820,7 +785,7 @@

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

<del>- * Displays form token for unfiltered comments.

</del><ins>+ * Display form token for unfiltered comments.

</ins><span class="cx">  *

</span><span class="cx">  * Will only display nonce token if the current user has permissions for

<span class="cx">  * unfiltered html. Won't display the token for other users.

</span><span class="lines">@@ -832,7 +797,6 @@

</span><span class="cx">  * Backported to 2.0.10.

</span><span class="cx">  *

</span><span class="cx">  * @since 2.1.3

</span><del>- * @uses $post Gets the ID of the current post for the token

</del><span class="cx">  */

</span><span class="cx"> function wp_comment_form_unfiltered_html_nonce() {

</span><span class="cx">  $post = get_post();

</span><span class="lines">@@ -845,7 +809,7 @@

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

<del>- * Loads the comment template specified in $file.

</del><ins>+ * Load the comment template specified in $file.

</ins><span class="cx">  *

</span><span class="cx">  * Will not display the comments template if not on single post or page, or if

<span class="cx">  * the post does not have comments.

</span><span class="lines">@@ -860,15 +824,14 @@

</span><span class="cx">  * default theme. If either does not exist, then the WordPress process will be

<span class="cx">  * halted. It is advised for that reason, that the default theme is not deleted.

</span><span class="cx">  *

</span><del>- * @since 1.5.0

- * @global array $comment List of comment objects for the current post

- * @uses $wpdb

- * @uses $post

</del><ins>+ * @todo Document globals

</ins><span class="cx">  * @uses $withcomments Will not try to get the comments if the post has none.

</span><span class="cx">  *

</span><del>- * @param string $file Optional, default '/comments.php'. The file to load

- * @param bool $separate_comments Optional, whether to separate the comments by comment type. Default is false.

- * @return null Returns null if no comments appear

</del><ins>+ * @since 1.5.0

+ *

+ * @param string $file              Optional. The file to load. Default '/comments.php'.

+ * @param bool   $separate_comments Optional. Whether to separate the comments by comment type. Default false.

+ * @return null Returns null if no comments appear.

</ins><span class="cx">  */

</span><span class="cx"> function comments_template( $file = '/comments.php', $separate_comments = false ) {

</span><span class="cx">  global $wp_query, $withcomments, $post, $wpdb, $id, $comment, $user_login, $user_ID, $user_identity, $overridden_cpage;

</span><span class="lines">@@ -942,7 +905,7 @@

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

<del>- * Displays the JS popup script to show a comment.

</del><ins>+ * Display the JS popup script to show a comment.

</ins><span class="cx">  *

</span><span class="cx">  * If the $file parameter is empty, then the home page is assumed. The defaults

<span class="cx">  * for the window are 400px by 400px.

</span><span class="lines">@@ -950,15 +913,16 @@

</span><span class="cx">  * For the comment link popup to work, this function has to be called or the

<span class="cx">  * normal comment link will be assumed.

</span><span class="cx">  *

<ins>+ * @global string $wpcommentspopupfile  The URL to use for the popup window.

+ * @global int    $wpcommentsjavascript Whether to use JavaScript. Set when function is called.

+ *

</ins><span class="cx">  * @since 0.71

</span><del>- * @global string $wpcommentspopupfile The URL to use for the popup window

- * @global int $wpcommentsjavascript Whether to use JavaScript. Set when function is called

</del><span class="cx">  *

</span><del>- * @param int $width Optional. The width of the popup window

- * @param int $height Optional. The height of the popup window

- * @param string $file Optional. Sets the location of the popup window

</del><ins>+ * @param int $width  Optional. The width of the popup window. Default 400.

+ * @param int $height Optional. The height of the popup window. Default 400.

+ * @param string $file Optional. Sets the location of the popup window.

</ins><span class="cx">  */

</span><del>-function comments_popup_script($width=400, $height=400, $file='') {

</del><ins>+function comments_popup_script( $width = 400, $height = 400, $file = '' ) {

</ins><span class="cx">   global $wpcommentspopupfile, $wpcommentsjavascript;

</span><span class="cx"> 

</span><span class="cx">  if (empty ($file)) {

</span><span class="lines">@@ -978,16 +942,16 @@

</span><span class="cx">  * Is not meant to be displayed on single posts and pages. Should be used on the

</span><span class="cx">  * lists of posts

</span><span class="cx">  *

<ins>+ * @global string $wpcommentspopupfile  The URL to use for the popup window.

+ * @global int    $wpcommentsjavascript Whether to use JavaScript. Set when function is called.

+ *

</ins><span class="cx">  * @since 0.71

</span><del>- * @uses $wpcommentspopupfile

- * @uses $wpcommentsjavascript

- * @uses $post

</del><span class="cx">  *

</span><del>- * @param string $zero The string to display when no comments

- * @param string $one The string to display when only one comment is available

- * @param string $more The string to display when there are more than one comment

- * @param string $css_class The CSS class to use for comments

- * @param string $none The string to display when comments have been turned off

</del><ins>+ * @param string $zero      Optional. The string to display when no comments. Default false.

+ * @param string $one       Optional. The string to display when only one comment is available. Default false.

+ * @param string $more      Optional. The string to display when there are more than one comment. Default false.

+ * @param string $css_class Optional. The CSS class to use for comments. Default empty.

+ * @param string $none      Optional. The string to display when comments have been turned off. Default false.

</ins><span class="cx">  * @return null Returns null on single posts and pages.

</span><span class="cx">  */

</span><span class="cx"> function comments_popup_link( $zero = false, $one = false, $more = false, $css_class = '', $none = false ) {

</span><span class="lines">@@ -1046,26 +1010,24 @@

</span><span class="cx">  * @since 2.7.0

</span><span class="cx">  *

</span><span class="cx">  * @param array $args {

<del>- *     Override default options.

</del><ins>+ *     Optional. Override default arguments.

</ins><span class="cx">  *

<del>- *     @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.

</del><ins>+ *     @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 '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 'respond'.

+ *     @type string 'reply_text' The text of the Reply link. Default 'Reply'.

+ *     @type string 'login_text' The text of the link to reply if logged out. Default '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 0.

+ *     @type string 'before'     The text or HTML to add before the reply link. Default empty.

+ *     @type string 'after'      The text or HTML to add after the reply link. Default empty.

</ins><span class="cx">  * }

<del>- * @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.

</del><ins>+ * @param int         $comment Optional. Comment being replied to. Default current comment.

+ * @param int|WP_Post $post    Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.

+ * @return mixed Link to show comment form, if successful. False, if comments are closed.

</ins><span class="cx">  */

</span><span class="cx"> function get_comment_reply_link($args = array(), $comment = null, $post = null) {

</span><span class="cx"> 

</span><span class="lines">@@ -1120,12 +1082,11 @@

<span class="cx">  * Displays the HTML content for reply to comment link.

</span><span class="cx">  *

</span><span class="cx">  * @since 2.7.0

</span><del>- * @see get_comment_reply_link() Echoes result

</del><span class="cx">  *

<del>- * @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.

</del><ins>+ * @param array       $args    Optional. Override default options, @see get_comment_reply_link()

+ * @param int         $comment Optional. Comment being replied to. Default current comment.

+ * @param int|WP_Post $post    Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.

+ * @return mixed Link to show comment form, if successful. False, if comments are closed.

</ins><span class="cx">  */

</span><span class="cx"> function comment_reply_link($args = array(), $comment = null, $post = null) {

</span><span class="cx">  echo get_comment_reply_link($args, $comment, $post);

</span><span class="lines">@@ -1134,19 +1095,22 @@

</span><span class="cx"> /**

<span class="cx">  * Retrieve HTML content for reply to post link.

</span><span class="cx">  *

</span><del>- * 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.

</del><ins>+ * @since 2.7.0

</ins><span class="cx">  *

<del>- * @todo See get_comment_reply_link() for a template of the args docblock.

</del><ins>+ * @param array $args {

+ *     Optional. Override default arguments.

</ins><span class="cx">  *

</span><del>- * @since 2.7.0

- *

- * @param array $args Optional. Override default options.

- * @param int|object $post Optional. Post that the comment is going to be displayed on. Defaults to current post.

</del><ins>+ *     @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 'post'.

+ *     @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 'Leave a Comment'.

+ *     @type string 'login_text' The text of the link to reply if logged out. Default is 'Log in to leave a Comment'.

+ *     @type string 'before'     The text or HTML to add before the reply link. Default empty.

+ *     @type string 'after'      The text or HTML to add after the reply link. Default empty.

+ * }

+ * @param int|WP_Post $post    Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.

</ins><span class="cx">  * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.

</span><span class="cx">  */

</span><span class="cx"> function get_post_reply_link($args = array(), $post = null) {

</span><span class="lines">@@ -1179,8 +1143,8 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 2.7.0

</span><span class="cx">  *

<del>- * @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.

</del><ins>+ * @param array       $args Optional. Override default options, @see get_post_reply_link()

+ * @param int|WP_Post $post Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.

</ins><span class="cx">  * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.

</span><span class="cx">  */

</span><span class="cx"> function post_reply_link($args = array(), $post = null) {

</span><span class="lines">@@ -1192,9 +1156,9 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 2.7.0

</span><span class="cx">  *

<del>- * @param string $text Optional. Text to display for cancel reply link.

</del><ins>+ * @param string $text Optional. Text to display for cancel reply link. Default empty.

</ins><span class="cx">  */

</span><del>-function get_cancel_comment_reply_link($text = '') {

</del><ins>+function get_cancel_comment_reply_link( $text = '' ) {

</ins><span class="cx">   if ( empty($text) )

</span><span class="cx">          $text = __('Click here to cancel reply.');

</span><span class="cx"> 

</span><span class="lines">@@ -1208,9 +1172,9 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 2.7.0

</span><span class="cx">  *

<del>- * @param string $text Optional. Text to display for cancel reply link.

</del><ins>+ * @param string $text Optional. Text to display for cancel reply link. Default empty.

</ins><span class="cx">  */

</span><del>-function cancel_comment_reply_link($text = '') {

</del><ins>+function cancel_comment_reply_link( $text = '' ) {

</ins><span class="cx">   echo get_cancel_comment_reply_link($text);

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="lines">@@ -1219,6 +1183,7 @@

</span><span class="cx">  *

</span><span class="cx">  * @since 3.0.0

</span><span class="cx">  *

<ins>+ * @param int $id Optional. Post ID. Default current post ID.

</ins><span class="cx">  * @return string Hidden input HTML for replying to comments

</span><span class="cx">  */

</span><span class="cx"> function get_comment_id_fields( $id = 0 ) {

</span><span class="lines">@@ -1235,20 +1200,24 @@

<span class="cx">  * Output hidden input HTML for replying to comments.

</span><span class="cx">  *

</span><span class="cx">  * @since 2.7.0

</span><del>- * @see get_comment_id_fields() Echoes result

</del><ins>+ *

+ * @param int $id Optional. Post ID. Default current post ID.

</ins><span class="cx">  */

</span><span class="cx"> function comment_id_fields( $id = 0 ) {

</span><span class="cx">  echo get_comment_id_fields( $id );

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

<del>- * Display text based on comment reply status. Only affects users with Javascript disabled.

</del><ins>+ * Display text based on comment reply status.

</ins><span class="cx">  *

<ins>+ * Only affects users with Javascript disabled.

+ *

</ins><span class="cx">  * @since 2.7.0

</span><span class="cx">  *

<del>- * @param string $noreplytext Optional. Text to display when not replying to a comment.

- * @param string $replytext Optional. Text to display when replying to a comment. Accepts "%s" for the author of the comment being replied to.

- * @param string $linktoparent Optional. Boolean to control making the author's name a link to their comment.

</del><ins>+ * @param string $noreplytext  Optional. Text to display when not replying to a comment. Default false.

+ * @param string $replytext    Optional. Text to display when replying to a comment.

+ *                             Default false. Accepts "%s" for the author of the comment being replied to.

+ * @param string $linktoparent Optional. Boolean to control making the author's name a link to their comment. Default true.

</ins><span class="cx">  */

</span><span class="cx"> function comment_form_title( $noreplytext = false, $replytext = false, $linktoparent = true ) {

</span><span class="cx">  global $comment;

</span><span class="lines">@@ -1536,17 +1505,34 @@

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

</span><del>- * List comments

</del><ins>+ * List comments.

</ins><span class="cx">  *

</span><del>- * Used in the comments.php template to list comments for a particular post

</del><ins>+ * Used in the comments.php template to list comments for a particular post.

</ins><span class="cx">  *

</span><span class="cx">  * @since 2.7.0

</span><del>- * @uses Walker_Comment

</del><span class="cx">  *

</span><del>- * @param string|array $args Formatting options

- * @param array $comments Optional array of comment objects. Defaults to $wp_query->comments

</del><ins>+ * @param string|array $args {

+ *     Optional. Formatting options.

+ *

+ *     @type string 'walker'            The Walker class used to list comments. Default null.

+ *     @type int    'max_depth'         The maximum comments depth. Default empty.

+ *     @type string 'style'             The style of list ordering. Default 'ul'. Accepts 'ul', 'ol'.

+ *     @type string 'callback'          Callback function to use. Default null.

+ *     @type string 'end-callback'      Callback function to use at the end. Default null.

+ *     @type string 'type'              Type of comments to list.

+ *                                      Default 'all'. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'.

+ *     @type int    'page'              Page ID to list comments for. Default empty.

+ *     @type int    'per_page'          Number of comments to list per page. Default empty.

+ *     @type int    'avatar_size'       Height and width dimensions of the avatar size. Default 32.

+ *     @type string 'reverse_top_level' Ordering of the listed comments. Default null. Accepts 'desc', 'asc'.

+ *     @type bool   'reverse_children'  Whether to reverse child comments in the list. Default null.

+ *     @type string 'format'            How to format the comments list.

+ *                                      Default 'html5' if the theme supports it. Accepts 'html5', 'xhtml'.

+ *     @type bool   'short_ping'        Whether to output short pings. Default false.

+ * }

+ * @param array $comments Optional. Array of comment objects. @see WP_Query->comments

</ins><span class="cx">  */

</span><del>-function wp_list_comments($args = array(), $comments = null ) {

</del><ins>+function wp_list_comments( $args = array(), $comments = null ) {

</ins><span class="cx">   global $wp_query, $comment_alt, $comment_depth, $comment_thread_alt, $overridden_cpage, $in_comment_loop;

</span><span class="cx"> 

</span><span class="cx">  $in_comment_loop = true;

</span><span class="lines">@@ -1643,7 +1629,8 @@

</span><span class="cx"> }

</span><span class="cx"> 

</span><span class="cx"> /**

<del>- * Outputs a complete commenting form for use within a template.

</del><ins>+ * Output a complete commenting form for use within a template.

+ *

</ins><span class="cx">  * Most strings and form fields may be controlled through the $args array passed

</span><span class="cx">  * into the function, while you may also choose to use the comment_form_default_fields

</span><span class="cx">  * filter to modify the array of default fields if you'd just like to add a new

</span><span class="lines">@@ -1652,9 +1639,10 @@

<span class="cx">  * in the array of fields.

</span><span class="cx">  *

</span><span class="cx">  * @since 3.0.0

</span><del>- * @param array $args Options for strings, fields etc in the form

- * @param mixed $post_id Post ID to generate the form for, uses the current post if null

- * @return void

</del><ins>+ *

+ * @todo Fully document $args

+ * @param array       $args    Optional. Options for strings, fields etc. in the form.

+ * @param int|WP_Post $post_id Optional. Post ID or WP_Post object to generate the form for. Default current post.

</ins><span class="cx">  */

</span><span class="cx"> function comment_form( $args = array(), $post_id = null ) {

</span><span class="cx">  if ( null === $post_id )

</span></span></pre>

</div>

</div>

</body>

</html>