Make WordPress Core

Ticket #27083: 27083.diff

File 27083.diff, 45.7 KB (added by DrewAPicture, 10 years ago)

All the docs + standards

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

     
    7676         *
    7777         * @since 1.5.0
    7878         *
    79          * @param string $comment->comment_author_email The comment author's email address.
     79         * @param string $comment_author_email The comment author's email address.
    8080         */
    8181        return apply_filters( 'get_comment_author_email', $comment->comment_author_email );
    8282}
     
    119119
    120120 * @since 0.71
    121121 *
    122  * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.
    123  * @param string $before   Optional. The text or HTML to display before the email link.Default empty.
    124  * @param string $after    Optional. The text or HTML to display after the email link. Default empty.
     122 * @param string $linktext Optional. Text to display instead of the comment author's email address.
     123 *                         Default empty.
     124 * @param string $before   Optional. Text or HTML to display before the email link.Default empty.
     125 * @param string $after    Optional. Text or HTML to display after the email link. Default empty.
    125126 */
    126127function comment_author_email_link( $linktext = '', $before = '', $after = '' ) {
    127128        if ( $link = get_comment_author_email_link( $linktext, $before, $after ) )
     
    141142 *
    142143 * @since 2.7.0
    143144 *
    144  * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.
    145  * @param string $before   Optional. The text or HTML to display before the email link. Default empty.
    146  * @param string $after    Optional. The text or HTML to display after the email link. Default empty.
     145 * @param string $linktext Optional. Text to display instead of the comment author's email address.
     146 *                         Default empty.
     147 * @param string $before   Optional. Text or HTML to display before the email link. Default empty.
     148 * @param string $after    Optional. Text or HTML to display after the email link. Default empty.
    147149 */
    148150function get_comment_author_email_link( $linktext = '', $before = '', $after = '' ) {
    149151        global $comment;
     
    151153         * Filter the comment author's email for display.
    152154         *
    153155         * Care should be taken to protect the email address and assure that email
    154          * harvesters do not capture your commentors' email address.
     156         * harvesters do not capture your commenters' email address.
    155157         *
    156158         * @since 1.2.0
    157159         *
    158          * @param string $comment->comment_author_email The comment author's email address.
     160         * @param string $comment_author_email The comment author's email address.
    159161         */
    160162        $email = apply_filters( 'comment_email', $comment->comment_author_email );
    161163        if ((!empty($email)) && ($email != '@')) {
     
    177179 *
    178180 * @since 1.5.0
    179181 *
    180  * @param int $comment_ID Optional. The ID of the comment for which to get the author's link. Default current comment.
     182 * @param int $comment_ID ID of the comment for which to get the author's link.
     183 *                        Default current comment.
    181184 * @return string The comment author name or HTML link for author's URL.
    182185 */
    183186function get_comment_author_link( $comment_ID = 0 ) {
     
    194197         *
    195198         * @since 1.5.0
    196199         *
    197          * @param string $return The HTML-formatted comment author link. Empty for an invalid URL.
     200         * @param string $return The HTML-formatted comment author link.
     201         *                       Empty for an invalid URL.
    198202         */
    199203        return apply_filters( 'get_comment_author_link', $return );
    200204}
     
    203207 * Display the html link to the url of the author of the current comment.
    204208 *
    205209 * @since 0.71
     210 *
    206211 * @see get_comment_author_link() Echoes result
    207212 *
    208  * @param int $comment_ID Optional. The ID of the comment for which to print the author's link. Default current comment.
     213 * @param int $comment_ID ID of the comment for which to print the author's
     214 *                        link. Default current comment.
    209215 */
    210216function comment_author_link( $comment_ID = 0 ) {
    211217        echo get_comment_author_link( $comment_ID );
     
    216222 *
    217223 * @since 1.5.0
    218224 *
    219  * @param int $comment_ID Optional. The ID of the comment for which to get the author's IP address. Default current comment.
    220  * @return string The comment author's IP address.
     225 * @param int $comment_ID ID of the comment for which to get the author's IP
     226 *                        address. Default current comment.
     227 * @return string Comment author's IP address.
    221228 */
    222229function get_comment_author_IP( $comment_ID = 0 ) {
    223230        $comment = get_comment( $comment_ID );
     
    227234         *
    228235         * @since 1.5.0
    229236         *
    230          * @param string $comment->comment_author_IP The comment author's IP address.
     237         * @param string $comment_author_IP The comment author's IP address.
    231238         */
    232239        return apply_filters( 'get_comment_author_IP', $comment->comment_author_IP );
    233240}
     
    237244 *
    238245 * @since 0.71
    239246 *
    240  * @param int $comment_ID Optional. The ID of the comment for which to print the author's IP address. Default current comment.
     247 * @param int $comment_ID ID of the comment for which to print the author's IP
     248 *                        address. Default current comment.
    241249 */
    242250function comment_author_IP( $comment_ID = 0 ) {
    243251        echo get_comment_author_IP( $comment_ID );
     
    248256 *
    249257 * @since 1.5.0
    250258 *
    251  * @param int $comment_ID Optional. The ID of the comment for which to get the author's URL. Default current comment.
     259 * @param int $comment_ID ID of the comment for which to get the author's URL.
     260 *                        Default current comment.
    252261 * @return string
    253262 */
    254263function get_comment_author_url( $comment_ID = 0 ) {
     
    270279 *
    271280 * @since 0.71
    272281 *
    273  * @param int $comment_ID Optional. The ID of the comment for which to print the author's URL. Default current comment.
     282 * @param int $comment_ID ID of the comment for which to print the author's URL.
     283 *                        Default current comment.
    274284 */
    275285function comment_author_url( $comment_ID = 0 ) {
    276286        $author_url = get_comment_author_url( $comment_ID );
     
    296306 *
    297307 * @since 1.5.0
    298308 *
    299  * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.
    300  * @param string $before   Optional. The text or HTML to display before the email link. Default empty.
    301  * @param string $after    Optional. The text or HTML to display after the email link. Default empty.
     309 * @param string $linktext Optional. The text to display instead of the comment
     310 *                         author's email address. Default empty.
     311 * @param string $before   Optional. The text or HTML to display before the email link.
     312 *                         Default empty.
     313 * @param string $after    Optional. The text or HTML to display after the email link.
     314 *                         Default empty.
    302315 * @return string The HTML link between the $before and $after parameters.
    303316 */
    304317function get_comment_author_url_link( $linktext = '', $before = '', $after = '' ) {
     
    325338 *
    326339 * @since 0.71
    327340 *
    328  * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.
    329  * @param string $before   Optional. The text or HTML to display before the email link. Default empty.
    330  * @param string $after    Optional. The text or HTML to display after the email link. Default empty.
     341 * @param string $linktext Optional. Text to display instead of the comment author's
     342 *                         email address. Default empty.
     343 * @param string $before   Optional. Text or HTML to display before the email link.
     344 *                         Default empty.
     345 * @param string $after    Optional. Text or HTML to display after the email link.
     346 *                         Default empty.
    331347 */
    332348function comment_author_url_link( $linktext = '', $before = '', $after = '' ) {
    333349        echo get_comment_author_url_link( $linktext, $before, $after );
    334350}
    335351
    336352/**
    337  * Generates semantic classes for each comment element
     353 * Generates semantic classes for each comment element.
    338354 *
    339355 * @since 2.7.0
    340356 *
    341  * @param string|array $class      Optional. One or more classes to add to the class list. Default empty.
    342  * @param int          $comment_id Optional. Comment ID. Default current comment.
    343  * @param int|WP_Post  $post_id    Optional. Post ID or WP_Post object. Default current post.
    344  * @param bool         $echo       Optional. Whether comment_class should echo or return. Default true.
     357 * @param string|array $class      Optional. One or more classes to add to the class list.
     358 *                                 Default empty.
     359 * @param int          $comment_id Comment ID. Default current comment.
     360 * @param int|WP_Post  $post_id    Post ID or WP_Post object. Default current post.
     361 * @param bool         $echo       Optional. Whether to cho or return the output.
     362 *                                 Default true.
    345363 */
    346364function comment_class( $class = '', $comment_id = null, $post_id = null, $echo = true ) {
    347365        // Separates classes with a single space, collates classes for comment DIV
     
    353371}
    354372
    355373/**
    356  * Returns the classes for the comment div as an array
     374 * Returns the classes for the comment div as an array.
    357375 *
    358376 * @since 2.7.0
    359377 *
    360378 * @param string|array $class      Optional. One or more classes to add to the class list. Default empty.
    361  * @param int          $comment_id Optional. Comment ID. Default current comment.
    362  * @param int|WP_Post  $post_id    Optional. Post ID or WP_Post object. Default current post.
     379 * @param int          $comment_id Comment ID. Default current comment.
     380 * @param int|WP_Post  $post_id    Post ID or WP_Post object. Default current post.
    363381 * @return array An array of classes.
    364382 */
    365383function get_comment_class( $class = '', $comment_id = null, $post_id = null ) {
     
    440458 * @since 1.5.0
    441459 *
    442460 * @param string $d          Optional. The format of the date. Default user's setting.
    443  * @param int    $comment_ID Optional. The ID of the comment for which to get the date. Default current comment.
     461 * @param int    $comment_ID ID of the comment for which to get the date. Default current comment.
    444462 * @return string The comment's date.
    445463 */
    446464function get_comment_date( $d = '', $comment_ID = 0 ) {
     
    466484 * @since 0.71
    467485 *
    468486 * @param string $d          Optional. The format of the date. Default user's settings.
    469  * @param int    $comment_ID Optional. The ID of the comment for which to print the date. Default current comment.
     487 * @param int    $comment_ID ID of the comment for which to print the date. Default current comment.
    470488 */
    471489function comment_date( $d = '', $comment_ID = 0 ) {
    472490        echo get_comment_date( $d, $comment_ID );
     
    481499 *
    482500 * @since 1.5.0
    483501 *
    484  * @param int $comment_ID Optional. The ID of the comment for which to get the excerpt. Default current comment.
     502 * @param int $comment_ID ID of the comment for which to get the excerpt.
     503 *                        Default current comment.
    485504 * @return string The maybe truncated comment with 20 words or less.
    486505 */
    487506function get_comment_excerpt( $comment_ID = 0 ) {
     
    508527 *
    509528 * @since 1.2.0
    510529 *
    511  * @param int $comment_ID Optional. The ID of the comment for which to print the excerpt. Default current comment.
     530 * @param int $comment_ID ID of the comment for which to print the excerpt.
     531 *                        Default current comment.
    512532 */
    513533function comment_excerpt( $comment_ID = 0 ) {
    514534        $comment_excerpt = get_comment_excerpt($comment_ID);
     
    536556         *
    537557         * @since 1.5.0
    538558         *
    539          * @param int $comment->comment_ID The current comment ID.
     559         * @param int $comment_ID The current comment ID.
    540560         */
    541561        return apply_filters( 'get_comment_ID', $comment->comment_ID );
    542562}
     
    555575 *
    556576 * @since 1.5.0
    557577 *
    558  * @param mixed $comment Optional. Comment to retrieve. Default current comment.
    559  * @param array $args    Optional. An array of arguments to override the defaults. @see get_page_of_comment()
     578 * @see get_page_of_comment()
     579 *
     580 * @param mixed $comment Comment to retrieve. Default current comment.
     581 * @param array $args    Optional. An array of arguments to override the defaults.
    560582 * @return string The permalink to the given comment.
    561583 */
    562584function get_comment_link( $comment = null, $args = array() ) {
     
    600622         *
    601623         * @since 2.8.0
    602624         *
     625         * @see get_page_of_comment()
     626         *
    603627         * @param string $link    The comment permalink with '#comment-$id' appended.
    604628         * @param object $comment The current comment object.
    605          * @param array  $args    An array of arguments to override the defaults. @see get_page_of_comment()
     629         * @param array  $args    An array of arguments to override the defaults.
    606630         */
    607631        return apply_filters( 'get_comment_link', $link, $comment, $args );
    608632}
     
    612636 *
    613637 * @since 1.5.0
    614638 *
    615  * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.
     639 * @param int|WP_Post $post_id Post ID or WP_Post object. Default current post.
    616640 * @return string The link to the comments.
    617641 */
    618642function get_comments_link( $post_id = 0 ) {
     
    622646         *
    623647         * @since
    624648         *
    625          * @param string      $comments_link The post comments permalink with '#comments' appended.
    626          * @param int|WP_Post $post_id       The post ID or WP_Post object.
     649         * @param string      $comments_link Post comments permalink with '#comments' appended.
     650         * @param int|WP_Post $post_id       Post ID or WP_Post object.
    627651         */
    628652        return apply_filters( 'get_comments_link', $comments_link, $post_id );
    629653}
     
    649673 *
    650674 * @since 1.5.0
    651675 *
    652  * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.
     676 * @param int|WP_Post $post_id Post ID or WP_Post object. Default current post.
    653677 * @return int The number of comments a post has.
    654678 */
    655679function get_comments_number( $post_id = 0 ) {
     
    669693         *
    670694         * @since 1.5.0
    671695         *
    672          * @param int         $count   The number of comments a post has.
    673          * @param int|WP_Post $post_id The post ID or WP_Post object.
     696         * @param int         $count   Nnumber of comments a post has.
     697         * @param int|WP_Post $post_id Post ID or WP_Post object.
    674698         */
    675699        return apply_filters( 'get_comments_number', $count, $post_id );
    676700}
     
    703727         *
    704728         * @since 1.5.0
    705729         *
    706          * @param string $output A translatable string formatted based on whether the count is equal to 0, 1, or 1+. @see _n()
     730         * @see _n()
     731         *
     732         * @param string $output A translatable string formatted based on whether the count
     733         *                       is equal to 0, 1, or 1+.
    707734         * @param int    $number The number of post comments.
    708735         */
    709736        echo apply_filters( 'comments_number', $output, $number );
     
    714741 *
    715742 * @since 1.5.0
    716743 *
    717  * @param int   $comment_ID Optional. The ID of the comment for which to get the text. Default current comment.
    718  * @param array $args       Optional. An array of arguments. @see Walker_Comment::comment()
     744 * @see Walker_Comment::comment()
     745 *
     746 * @param int   $comment_ID ID of the comment for which to get the text. Default current comment.
     747 * @param array $args       Optional. An array of arguments. Default empty.
    719748 * @return string The comment content.
    720749 */
    721750function get_comment_text( $comment_ID = 0, $args = array() ) {
     
    726755         *
    727756         * @since 1.5.0
    728757         *
    729          * @param string $comment->comment_content The text of the comment.
    730          * @param object $comment                  The comment object.
    731          * @param array  $args                     An array of arguments. @see Walker_Comment::comment()
     758         * @see Walker_Comment::comment()
     759         *
     760         * @param string $comment_content Text of the comment.
     761         * @param object $comment         The comment object.
     762         * @param array  $args            An array of arguments.
    732763         */
    733764        return apply_filters( 'get_comment_text', $comment->comment_content, $comment, $args );
    734765}
     
    738769 *
    739770 * @since 0.71
    740771 *
    741  * @param int   $comment_ID Optional. The ID of the comment for which to print the text.
    742  *                          Default 0.
    743  * @param array $args       Optional. An array of arguments. @see Walker_Comment::comment()
    744  *                          Default empty array.
     772 * @see Walker_Comment::comment()
     773 *
     774 * @param int   $comment_ID ID of the comment for which to print the text. Default 0.
     775 * @param array $args       Optional. An array of arguments. Default empty array. Default empty.
    745776 */
    746777function comment_text( $comment_ID = 0, $args = array() ) {
    747778        $comment = get_comment( $comment_ID );
     
    752783         *
    753784         * @since 1.2.0
    754785         *
    755          * @param string $comment_text The text of the current comment.
     786         * @see Walker_Comment::comment()
     787         *
     788         * @param string $comment_text Text of the current comment.
    756789         * @param object $comment      The comment object.
    757          * @param array  $args         An array of arguments. @see Walker_Comment::comment()
     790         * @param array  $args         An array of arguments.
    758791         */
    759792        echo apply_filters( 'comment_text', $comment_text, $comment, $args );
    760793}
     
    766799 *
    767800 * @param string $d         Optional. The format of the time. Default user's settings.
    768801 * @param bool   $gmt       Optional. Whether to use the GMT date. Default false.
    769  * @param bool   $translate Optional. Whether to translate the time (for use in feeds). Default true.
    770  * @return string The formatted time
     802 * @param bool   $translate Optional. Whether to translate the time (for use in feeds).
     803 *                          Default true.
     804 * @return string The formatted time.
    771805 */
    772806function get_comment_time( $d = '', $gmt = false, $translate = true ) {
    773807        global $comment;
     
    783817         * @since 1.5.0
    784818         *
    785819         * @param string|int $date      The comment time, formatted as a date string or Unix timestamp.
    786          * @param string     $d         The date format.
     820         * @param string     $d         Date format.
    787821         * @param bool       $gmt       Whether the GMT date is in use.
    788822         * @param bool       $translate Whether the time is translated.
    789823         */
     
    806840 *
    807841 * @since 1.5.0
    808842 *
    809  * @param int $comment_ID Optional. The ID of the comment for which to get the type. Default current comment.
    810  * @return string The comment type
     843 * @param int $comment_ID ID of the comment for which to get the type. Default current comment.
     844 * @return string The comment type.
    811845 */
    812846function get_comment_type( $comment_ID = 0 ) {
    813847        $comment = get_comment( $comment_ID );
     
    819853         *
    820854         * @since 1.5.0
    821855         *
    822          * @param string $comment->comment_type The type of comment, such as 'comment', 'pingback', or 'trackback'.
     856         * @param string $comment_type The type of comment, such as 'comment', 'pingback', or 'trackback'.
    823857         */
    824858        return apply_filters( 'get_comment_type', $comment->comment_type );
    825859}
     
    829863 *
    830864 * @since 0.71
    831865 *
    832  * @param string $commenttxt   Optional. The string to display for comment type. Default false.
    833  * @param string $trackbacktxt Optional. The string to display for trackback type. Default false.
    834  * @param string $pingbacktxt  Optional. The string to display for pingback type. Default false.
     866 * @param string $commenttxt   Optional. String to display for comment type. Default false.
     867 * @param string $trackbacktxt Optional. String to display for trackback type. Default false.
     868 * @param string $pingbacktxt  Optional. String to display for pingback type. Default false.
    835869 */
    836870function comment_type( $commenttxt = false, $trackbacktxt = false, $pingbacktxt = false ) {
    837871        if ( false === $commenttxt ) $commenttxt = _x( 'Comment', 'noun' );
     
    883917 * @since 0.71
    884918 *
    885919 * @param bool $deprecated_echo Not used.
    886  * @return void|string Should only be used to echo the trackback URL, use get_trackback_url() for the result instead.
     920 * @return void|string Should only be used to echo the trackback URL, use get_trackback_url()
     921 *                     for the result instead.
    887922 */
    888923function trackback_url( $deprecated_echo = true ) {
    889924        if ( $deprecated_echo !== true )
     
    929964 *
    930965 * @since 1.5.0
    931966 *
    932  * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.
     967 * @param int|WP_Post $post_id Post ID or WP_Post object. Default current post.
    933968 * @return bool True if the comments are open.
    934969 */
    935970function comments_open( $post_id = null ) {
     
    954989 *
    955990 * @since 1.5.0
    956991 *
    957  * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.
     992 * @param int|WP_Post $post_id Post ID or WP_Post object. Default current post.
    958993 * @return bool True if pings are accepted
    959994 */
    960995function pings_open( $post_id = null ) {
     
    10111046 * @since 1.5.0
    10121047 *
    10131048 * @param string $file              Optional. The file to load. Default '/comments.php'.
    1014  * @param bool   $separate_comments Optional. Whether to separate the comments by comment type. Default false.
     1049 * @param bool   $separate_comments Optional. Whether to separate the comments by comment type.
     1050 *                                  Default false.
    10151051 * @return null Returns null if no comments appear.
    10161052 */
    10171053function comments_template( $file = '/comments.php', $separate_comments = false ) {
     
    10251061
    10261062        $req = get_option('require_name_email');
    10271063
    1028         /**
     1064        /*
    10291065         * Comment author information fetched from the comment cookies.
    1030          *
    1031          * @uses wp_get_current_commenter()
     1066         * Uuses wp_get_current_commenter().
    10321067         */
    10331068        $commenter = wp_get_current_commenter();
    10341069
    1035         /**
     1070        /*
    10361071         * The name of the current comment author escaped for use in attributes.
     1072         * Escaped by sanitize_comment_cookies().
    10371073         */
    1038         $comment_author = $commenter['comment_author']; // Escaped by sanitize_comment_cookies()
     1074        $comment_author = $commenter['comment_author'];
    10391075
    1040         /**
     1076        /*
    10411077         * The email address of the current comment author escaped for use in attributes.
     1078         * Escaped by sanitize_comment_cookies().
    10421079         */
    1043         $comment_author_email = $commenter['comment_author_email'];  // Escaped by sanitize_comment_cookies()
     1080        $comment_author_email = $commenter['comment_author_email'];
    10441081
    1045         /**
     1082        /*
    10461083         * The url of the current comment author escaped for use in attributes.
    10471084         */
    10481085        $comment_author_url = esc_url($commenter['comment_author_url']);
     
    10561093                $comments = $wpdb->get_results($wpdb->prepare("SELECT * FROM $wpdb->comments WHERE comment_post_ID = %d AND ( comment_approved = '1' OR ( comment_author = %s AND comment_author_email = %s AND comment_approved = '0' ) ) ORDER BY comment_date_gmt", $post->ID, wp_specialchars_decode($comment_author,ENT_QUOTES), $comment_author_email));
    10571094        }
    10581095
    1059         // keep $comments for legacy's sake
    10601096        /**
    10611097         * Filter the comments array.
    10621098         *
    10631099         * @since 2.1.0
    10641100         *
    1065          * @param array $comments The array of comments supplied to the comments template.
    1066          * @param int   $post->ID The post ID.
     1101         * @param array $comments Array of comments supplied to the comments template.
     1102         * @param int   $post_ID  Post ID.
    10671103         */
    10681104        $wp_query->comments = apply_filters( 'comments_array', $comments, $post->ID );
    10691105        $comments = &$wp_query->comments;
     
    11361172/**
    11371173 * Displays the link to the comments popup window for the current post ID.
    11381174 *
    1139  * Is not meant to be displayed on single posts and pages. Should be used on the
    1140  * lists of posts
     1175 * Is not meant to be displayed on single posts and pages. Should be used
     1176 * on the lists of posts
    11411177 *
    11421178 * @global string $wpcommentspopupfile  The URL to use for the popup window.
    11431179 * @global int    $wpcommentsjavascript Whether to use JavaScript. Set when function is called.
    11441180 *
    11451181 * @since 0.71
    11461182 *
    1147  * @param string $zero      Optional. The string to display when no comments. Default false.
    1148  * @param string $one       Optional. The string to display when only one comment is available. Default false.
    1149  * @param string $more      Optional. The string to display when there are more than one comment. Default false.
    1150  * @param string $css_class Optional. The CSS class to use for comments. Default empty.
    1151  * @param string $none      Optional. The string to display when comments have been turned off. Default false.
     1183 * @param string $zero      Optional. String to display when no comments. Default false.
     1184 * @param string $one       Optional. String to display when only one comment is available.
     1185 *                          Default false.
     1186 * @param string $more      Optional. String to display when there are more than one comment.
     1187 *                          Default false.
     1188 * @param string $css_class Optional. CSS class to use for comments. Default empty.
     1189 * @param string $none      Optional. String to display when comments have been turned off.
     1190 *                          Default false.
    11521191 * @return null Returns null on single posts and pages.
    11531192 */
    11541193function comments_popup_link( $zero = false, $one = false, $more = false, $css_class = '', $none = false ) {
     
    12171256 * @param array $args {
    12181257 *     Optional. Override default arguments.
    12191258 *
    1220  *     @type string 'add_below'  The first part of the selector used to identify the comment to respond below. The resulting
    1221  *                               value is passed as the first parameter to addComment.moveForm(), concatenated
    1222  *                              as $add_below-$comment->comment_ID. Default 'comment'.
    1223  *     @type string 'respond_id' The selector identifying the responding comment. Passed as the third parameter to addComment.moveForm(),
    1224  *                               and appended to the link URL as a hash value. Default 'respond'.
    1225  *     @type string 'reply_text' The text of the Reply link. Default 'Reply'.
    1226  *     @type string 'login_text' The text of the link to reply if logged out. Default 'Log in to Reply'.
    1227  *     @type int    'depth'      The depth of the new comment. Must be greater than 0 and less than the value of the 'thread_comments_depth'
    1228  *                               option set in Settings > Discussion.
    1229  *                              Default 0.
    1230  *     @type string 'before'     The text or HTML to add before the reply link. Default empty.
    1231  *     @type string 'after'      The text or HTML to add after the reply link. Default empty.
     1259 *     @type string $add_below  The first part of the selector used to identify the comment to respond below.
     1260 *                              The resulting value is passed as the first parameter to addComment.moveForm(),
     1261 *                              concatenated as $add_below-$comment->comment_ID. Default 'comment'.
     1262 *     @type string $respond_id The selector identifying the responding comment. Passed as the third parameter
     1263 *                              to addComment.moveForm(), and appended to the link URL as a hash value.
     1264 *                              Default 'respond'.
     1265 *     @type string $reply_text The text of the Reply link. Default 'Reply'.
     1266 *     @type string $login_text The text of the link to reply if logged out. Default 'Log in to Reply'.
     1267 *     @type int    $depth'     The depth of the new comment. Must be greater than 0 and less than the value
     1268 *                              of the 'thread_comments_depth' option set in Settings > Discussion. Default 0.
     1269 *     @type string $before     The text or HTML to add before the reply link. Default empty.
     1270 *     @type string $after      The text or HTML to add after the reply link. Default empty.
    12321271 * }
    1233  * @param int         $comment Optional. Comment being replied to. Default current comment.
    1234  * @param int|WP_Post $post    Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.
     1272 * @param int         $comment Comment being replied to. Default current comment.
     1273 * @param int|WP_Post $post    Post ID or WP_Post object the comment is going to be displayed on.
     1274 *                             Default current post.
    12351275 * @return mixed Link to show comment form, if successful. False, if comments are closed.
    12361276 */
    12371277function get_comment_reply_link($args = array(), $comment = null, $post = null) {
     
    12731313         *
    12741314         * @since 2.7.0
    12751315         *
    1276          * @param string  $before  Text or HTML displayed before the reply link.
    12771316         * @param string  $link    The HTML markup for the comment reply link.
    1278          * @param string  $after   Text or HTML displayed after the reply link.
    12791317         * @param array   $args    An array of arguments overriding the defaults.
    12801318         * @param object  $comment The object of the comment being replied.
    12811319         * @param WP_Post $post    The WP_Post object.
     
    12881326 *
    12891327 * @since 2.7.0
    12901328 *
    1291  * @param array       $args    Optional. Override default options, @see get_comment_reply_link()
    1292  * @param int         $comment Optional. Comment being replied to. Default current comment.
    1293  * @param int|WP_Post $post    Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.
     1329 * @see get_comment_reply_link()
     1330 *
     1331 * @param array       $args    Optional. Override default options.
     1332 * @param int         $comment Comment being replied to. Default current comment.
     1333 * @param int|WP_Post $post    Post ID or WP_Post object the comment is going to be displayed on.
     1334 *                             Default current post.
    12941335 * @return mixed Link to show comment form, if successful. False, if comments are closed.
    12951336 */
    12961337function comment_reply_link($args = array(), $comment = null, $post = null) {
     
    13051346 * @param array $args {
    13061347 *     Optional. Override default arguments.
    13071348 *
    1308  *     @type string 'add_below'  The first part of the selector used to identify the comment to respond below.
    1309  *                               The resulting value is passed as the first parameter to addComment.moveForm(),
    1310  *                               concatenated as $add_below-$comment->comment_ID. Default is 'post'.
    1311  *     @type string 'respond_id' The selector identifying the responding comment. Passed as the third parameter
    1312  *                               to addComment.moveForm(), and appended to the link URL as a hash value. Default is 'respond'.
    1313  *     @type string 'reply_text' The text of the Reply link. Default is 'Leave a Comment'.
    1314  *     @type string 'login_text' The text of the link to reply if logged out. Default is 'Log in to leave a Comment'.
    1315  *     @type string 'before'     The text or HTML to add before the reply link. Default empty.
    1316  *     @type string 'after'      The text or HTML to add after the reply link. Default empty.
     1349 *     @type string $add_below  The first part of the selector used to identify the comment to respond below.
     1350 *                              The resulting value is passed as the first parameter to addComment.moveForm(),
     1351 *                              concatenated as $add_below-$comment->comment_ID. Default is 'post'.
     1352 *     @type string $respond_id The selector identifying the responding comment. Passed as the third parameter
     1353 *                              to addComment.moveForm(), and appended to the link URL as a hash value.
     1354 *                              Default 'respond'.
     1355 *     @type string $reply_text Text of the Reply link. Default is 'Leave a Comment'.
     1356 *     @type string $login_text Text of the link to reply if logged out. Default is 'Log in to leave a Comment'.
     1357 *     @type string $before     Text or HTML to add before the reply link. Default empty.
     1358 *     @type string $after      Text or HTML to add after the reply link. Default empty.
    13171359 * }
    1318  * @param int|WP_Post $post    Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.
     1360 * @param int|WP_Post $post    Optional. Post ID or WP_Post object the comment is going to be displayed on.
     1361 *                             Default current post.
    13191362 * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
    13201363 */
    13211364function get_post_reply_link($args = array(), $post = null) {
     
    13571400 *
    13581401 * @since 2.7.0
    13591402 *
    1360  * @param array       $args Optional. Override default options, @see get_post_reply_link()
    1361  * @param int|WP_Post $post Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.
     1403 * @see get_post_reply_link()
     1404 *
     1405 * @param array       $args Optional. Override default options,
     1406 * @param int|WP_Post $post Post ID or WP_Post object the comment is going to be displayed on.
     1407 *                          Default current post.
    13621408 * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
    13631409 */
    13641410function post_reply_link($args = array(), $post = null) {
     
    13861432         * @since 2.7.0
    13871433         *
    13881434         * @param string $formatted_link The HTML-formatted cancel comment reply link.
    1389          * @param string $link           The cancel comment reply link URL.
    1390          * @param string $text           The cancel comment reply link text.
     1435         * @param string $link           Cancel comment reply link URL.
     1436         * @param string $text           Cancel comment reply link text.
    13911437         */
    13921438        return apply_filters( 'cancel_comment_reply_link', $formatted_link, $link, $text );
    13931439}
     
    14491495 *
    14501496 * @since 2.7.0
    14511497 *
    1452  * @param string $noreplytext  Optional. Text to display when not replying to a comment. Default false.
     1498 * @param string $noreplytext  Optional. Text to display when not replying to a comment.
     1499 *                             Default false.
    14531500 * @param string $replytext    Optional. Text to display when replying to a comment.
    1454  *                             Default false. Accepts "%s" for the author of the comment being replied to.
    1455  * @param string $linktoparent Optional. Boolean to control making the author's name a link to their comment. Default true.
     1501 *                             Default false. Accepts "%s" for the author of the comment
     1502 *                             being replied to.
     1503 * @param string $linktoparent Optional. Boolean to control making the author's name a link
     1504 *                             to their comment. Default true.
    14561505 */
    14571506function comment_form_title( $noreplytext = false, $replytext = false, $linktoparent = true ) {
    14581507        global $comment;
     
    15731622         *  2.2
    15741623         *
    15751624         * @see Walker::display_element()
     1625         * @see wp_list_comments()
    15761626         *
    15771627         * @since 2.7.0
    15781628         *
     
    15801630         * @param array  $children_elements List of elements to continue traversing.
    15811631         * @param int    $max_depth         Max depth to traverse.
    15821632         * @param int    $depth             Depth of current element.
    1583          * @param array  $args              An array of arguments. @see wp_list_comments()
     1633         * @param array  $args              An array of arguments.
    15841634         * @param string $output            Passed by reference. Used to append additional content.
    15851635         * @return null Null on failure with no changes to parameters.
    15861636         */
     
    16081658        /**
    16091659         * Start the element output.
    16101660         *
     1661         * @since 2.7.0
     1662         *
    16111663         * @see Walker::start_el()
     1664         * @see wp_list_comments()
    16121665         *
    1613          * @since 2.7.0
    1614          *
    16151666         * @param string $output  Passed by reference. Used to append additional content.
    16161667         * @param object $comment Comment data object.
    16171668         * @param int    $depth   Depth of comment in reference to parents.
    1618          * @param array  $args    An array of arguments. @see wp_list_comments()
     1669         * @param array  $args    An array of arguments.
    16191670         */
    16201671        function start_el( &$output, $comment, $depth = 0, $args = array(), $id = 0 ) {
    16211672                $depth++;
     
    16471698        /**
    16481699         * Ends the element output, if needed.
    16491700         *
     1701         * @since 2.7.0
     1702         *
    16501703         * @see Walker::end_el()
     1704         * @see wp_list_comments()
    16511705         *
    1652          * @since 2.7.0
    1653          *
    16541706         * @param string $output  Passed by reference. Used to append additional content.
    16551707         * @param object $comment The comment object. Default current comment.
    16561708         * @param int    $depth   Depth of comment.
    1657          * @param array  $args    An array of arguments. @see wp_list_comments()
     1709         * @param array  $args    An array of arguments.
    16581710         */
    16591711        function end_el( &$output, $comment, $depth = 0, $args = array() ) {
    16601712                if ( !empty( $args['end-callback'] ) ) {
     
    16751727         * @access protected
    16761728         * @since 3.6.0
    16771729         *
     1730         * @see wp_list_comments()
     1731         *
    16781732         * @param object $comment The comment object.
    16791733         * @param int    $depth   Depth of comment.
    1680          * @param array  $args    An array of arguments. @see wp_list_comments()
     1734         * @param array  $args    An array of arguments.
    16811735         */
    16821736        protected function ping( $comment, $depth, $args ) {
    16831737                $tag = ( 'div' == $args['style'] ) ? 'div' : 'li';
     
    16951749         * @access protected
    16961750         * @since 3.6.0
    16971751         *
     1752         * @see wp_list_comments()
     1753         *
    16981754         * @param object $comment Comment to display.
    16991755         * @param int    $depth   Depth of comment.
    1700          * @param array  $args    An array of arguments. @see wp_list_comments()
     1756         * @param array  $args    An array of arguments.
    17011757         */
    17021758        protected function comment( $comment, $depth, $args ) {
    17031759                if ( 'div' == $args['style'] ) {
     
    17451801         * @access protected
    17461802         * @since 3.6.0
    17471803         *
     1804         * @see wp_list_comments()
     1805         *
    17481806         * @param object $comment Comment to display.
    17491807         * @param int    $depth   Depth of comment.
    1750          * @param array  $args    An array of arguments. @see wp_list_comments()
     1808         * @param array  $args    An array of arguments.
    17511809         */
    17521810        protected function html5_comment( $comment, $depth, $args ) {
    17531811                $tag = ( 'div' === $args['style'] ) ? 'div' : 'li';
     
    17931851 *
    17941852 * @since 2.7.0
    17951853 *
     1854 * @see WP_Query->comments
     1855 *
    17961856 * @param string|array $args {
    17971857 *     Optional. Formatting options.
    17981858 *
    1799  *     @type string 'walker'            The Walker class used to list comments. Default null.
    1800  *     @type int    'max_depth'         The maximum comments depth. Default empty.
    1801  *     @type string 'style'             The style of list ordering. Default 'ul'. Accepts 'ul', 'ol'.
    1802  *     @type string 'callback'          Callback function to use. Default null.
    1803  *     @type string 'end-callback'      Callback function to use at the end. Default null.
    1804  *     @type string 'type'              Type of comments to list.
    1805  *                                      Default 'all'. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'.
    1806  *     @type int    'page'              Page ID to list comments for. Default empty.
    1807  *     @type int    'per_page'          Number of comments to list per page. Default empty.
    1808  *     @type int    'avatar_size'       Height and width dimensions of the avatar size. Default 32.
    1809  *     @type string 'reverse_top_level' Ordering of the listed comments. Default null. Accepts 'desc', 'asc'.
    1810  *     @type bool   'reverse_children'  Whether to reverse child comments in the list. Default null.
    1811  *     @type string 'format'            How to format the comments list.
    1812  *                                      Default 'html5' if the theme supports it. Accepts 'html5', 'xhtml'.
    1813  *     @type bool   'short_ping'        Whether to output short pings. Default false.
    1814  *     @type bool   'echo'              Whether to echo the output or return it. Default true.
     1859 *     @type string $walker            The Walker class used to list comments. Default null.
     1860 *     @type int    $max_depth         The maximum comments depth. Default empty.
     1861 *     @type string $style             The style of list ordering. Default 'ul'. Accepts 'ul', 'ol'.
     1862 *     @type string $callback          Callback function to use. Default null.
     1863 *     @type string $end-callback      Callback function to use at the end. Default null.
     1864 *     @type string $type              Type of comments to list.
     1865 *                                     Default 'all'. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'.
     1866 *     @type int    $page              Page ID to list comments for. Default empty.
     1867 *     @type int    $per_page          Number of comments to list per page. Default empty.
     1868 *     @type int    $avatar_size       Height and width dimensions of the avatar size. Default 32.
     1869 *     @type string $reverse_top_level Ordering of the listed comments. Default null. Accepts 'desc', 'asc'.
     1870 *     @type bool   $reverse_children  Whether to reverse child comments in the list. Default null.
     1871 *     @type string $format            How to format the comments list.
     1872 *                                     Default 'html5' if the theme supports it. Accepts 'html5', 'xhtml'.
     1873 *     @type bool   $short_ping        Whether to output short pings. Default false.
     1874 *     @type bool   $echo              Whether to echo the output or return it. Default true.
    18151875 * }
    1816  * @param array $comments Optional. Array of comment objects. @see WP_Query->comments
     1876 * @param array $comments Optional. Array of comment objects.
    18171877 */
    18181878function wp_list_comments( $args = array(), $comments = null ) {
    18191879        global $wp_query, $comment_alt, $comment_depth, $comment_thread_alt, $overridden_cpage, $in_comment_loop;
     
    19321992 * @param array       $args {
    19331993 *     Optional. Default arguments and form fields to override.
    19341994 *
    1935  *     @type array 'fields' {
     1995 *     @type array $fields {
    19361996 *         Default comment fields, filterable by default via the 'comment_form_default_fields' hook.
    19371997 *
    1938  *         @type string 'author' The comment author field HTML.
    1939  *         @type string 'email'  The comment author email field HTML.
    1940  *         @type string 'url'    The comment author URL field HTML.
     1998 *         @type string $author Comment author field HTML.
     1999 *         @type string $email  Comment author email field HTML.
     2000 *         @type string $url    Comment author URL field HTML.
    19412001 *     }
    1942  *     @type string 'comment_field'        The comment textarea field HTML.
    1943  *     @type string 'must_log_in'          HTML element for a 'must be logged in to comment' message.
    1944  *     @type string 'logged_in_as'         HTML element for a 'logged in as <user>' message.
    1945  *     @type string 'comment_notes_before' HTML element for a message displayed before the comment form.
    1946  *                                         Default 'Your email address will not be published.'.
    1947  *     @type string 'comment_notes_after'  HTML element for a message displayed after the comment form.
    1948  *                                         Default 'You may use these HTML tags and attributes ...'.
    1949  *     @type string 'id_form'              The comment form element id attribute. Default 'commentform'.
    1950  *     @type string 'id_submit'            The comment submit element id attribute. Default 'submit'.
    1951  *     @type string 'title_reply'          The translatable 'reply' button label. Default 'Leave a Reply'.
    1952  *     @type string 'title_reply_to'       The translatable 'reply-to' button label. Default 'Leave a Reply to %s',
    1953  *                                         where %s is the author of the comment being replied to.
    1954  *     @type string 'cancel_reply_link'    The translatable 'cancel reply' button label. Default 'Cancel reply'.
    1955  *     @type string 'label_submit'         The translatable 'submit' button label. Default 'Post a comment'.
    1956  *     @type string 'format'               The comment form format. Default 'xhtml'. Accepts 'xhtml', 'html5'.
     2002 *     @type string $comment_field        The comment textarea field HTML.
     2003 *     @type string $must_log_in          HTML element for a 'must be logged in to comment' message.
     2004 *     @type string $logged_in_as         HTML element for a 'logged in as <user>' message.
     2005 *     @type string $comment_notes_before HTML element for a message displayed before the comment form.
     2006 *                                        Default 'Your email address will not be published.'.
     2007 *     @type string $comment_notes_after  HTML element for a message displayed after the comment form.
     2008 *                                        Default 'You may use these HTML tags and attributes ...'.
     2009 *     @type string $id_form              The comment form element id attribute. Default 'commentform'.
     2010 *     @type string $id_submit            The comment submit element id attribute. Default 'submit'.
     2011 *     @type string $title_reply          The translatable 'reply' button label. Default 'Leave a Reply'.
     2012 *     @type string $title_reply_to       The translatable 'reply-to' button label. Default 'Leave a Reply to %s',
     2013 *                                        where %s is the author of the comment being replied to.
     2014 *     @type string $cancel_reply_link    The translatable 'cancel reply' button label. Default 'Cancel reply'.
     2015 *     @type string $label_submit         The translatable 'submit' button label. Default 'Post a comment'.
     2016 *     @type string $format               The comment form format. Default 'xhtml'. Accepts 'xhtml', 'html5'.
    19572017 * }
    1958  * @param int|WP_Post $post_id Optional. Post ID or WP_Post object to generate the form for. Default current post.
     2018 * @param int|WP_Post $post_id Post ID or WP_Post object to generate the form for. Default current post.
    19592019 */
    19602020function comment_form( $args = array(), $post_id = null ) {
    19612021        if ( null === $post_id )
     
    20592119                                                         *
    20602120                                                         * @since 3.0.0
    20612121                                                         *
    2062                                                          * @param string $args['logged_in_as'] The logged-in-as HTML-formatted message.
    2063                                                          * @param array  $commenter            An array containing the comment author's username, email, and URL.
    2064                                                          * @param string $user_identity        If the commenter is a registered user, the display name, blank otherwise.
     2122                                                         * @param string $args_logged_in The logged-in-as HTML-formatted message.
     2123                                                         * @param array  $commenter      An array containing the comment author's
     2124                                                         *                               username, email, and URL.
     2125                                                         * @param string $user_identity  If the commenter is a registered user,
     2126                                                         *                               the display name, blank otherwise.
    20652127                                                         */
    20662128                                                        echo apply_filters( 'comment_form_logged_in', $args['logged_in_as'], $commenter, $user_identity );
    20672129                                                        ?>
     
    20712133                                                         *
    20722134                                                         * @since 3.0.0
    20732135                                                         *
    2074                                                          * @param array  $commenter     An array containing the comment author's username, email, and URL.
    2075                                                          * @param string $user_identity If the commenter is a registered user, the display name, blank otherwise.
     2136                                                         * @param array  $commenter     An array containing the comment author's
     2137                                                         *                              username, email, and URL.
     2138                                                         * @param string $user_identity If the commenter is a registered user,
     2139                                                         *                              the display name, blank otherwise.
    20762140                                                         */
    20772141                                                        do_action( 'comment_form_logged_in_after', $commenter, $user_identity );
    20782142                                                        ?>
     
    21122176                                                 *
    21132177                                                 * @since 3.0.0
    21142178                                                 *
    2115                                                  * @param string $args['comment_field'] The content of the comment textarea field.
     2179                                                 * @param string $args_comment_field The content of the comment textarea field.
    21162180                                                 */
    21172181                                                echo apply_filters( 'comment_form_field_comment', $args['comment_field'] );
    21182182                                                ?>