WordPress.org
Get WordPress

Make WordPress Core

Changeset 25567


Ignore:
Timestamp:
09/23/2013 04:15:41 AM (11 years ago)
Author:
DrewAPicture
Message:

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 #20495. See #25388.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r25562 r25567  
    1616 *
    1717 * @since 1.5.0
    18  * @uses apply_filters() Calls 'get_comment_author' hook on the comment author
    19  *
    20  * @param int $comment_ID The ID of the comment for which to retrieve the author. Optional.
     18 *
     19 * @param int $comment_ID Optional. The ID of the comment for which to retrieve the author. Default current comment.
    2120 * @return string The comment author
    2221 */
    … …  
    4039 *
    4140 * @since 0.71
    42  * @uses apply_filters() Calls 'comment_author' on comment author before displaying
    43  *
    44  * @param int $comment_ID The ID of the comment for which to print the author. Optional.
     41 *
     42 * @param int $comment_ID Optional. The ID of the comment for which to print the author. Default current comment.
    4543 */
    4644function comment_author( $comment_ID = 0 ) {
    … …  
    5351 *
    5452 * @since 1.5.0
    55  * @uses apply_filters() Calls the 'get_comment_author_email' hook on the comment author email
    56  * @uses $comment
    57  *
    58  * @param int $comment_ID The ID of the comment for which to get the author's email. Optional.
     53 *
     54 * @param int $comment_ID Optional. The ID of the comment for which to get the author's email. Default current comment.
    5955 * @return string The current comment author's email
    6056 */
    … …  
    7470 *
    7571 * @since 0.71
    76  * @uses apply_filters() Calls 'author_email' hook on the author email
    77  *
    78  * @param int $comment_ID The ID of the comment for which to print the author's email. Optional.
     72 *
     73 * @param int $comment_ID Optional. The ID of the comment for which to print the author's email. Default current comment.
    7974 */
    8075function comment_author_email( $comment_ID = 0 ) {
    … …  
    9186 * address and use it for their own means good and bad.
    9287 *
     88 * @global object $comment The current Comment row object
     89
    9390 * @since 0.71
    94  * @uses apply_filters() Calls 'comment_email' hook for the display of the comment author's email
    95  * @uses get_comment_author_email_link() For generating the link
    96  * @global object $comment The current Comment row object
    97  *
    98  * @param string $linktext The text to display instead of the comment author's email address
    99  * @param string $before The text or HTML to display before the email link.
    100  * @param string $after The text or HTML to display after the email link.
    101  */
    102 function comment_author_email_link($linktext='', $before='', $after='') {
     91 *
     92 * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.
     93 * @param string $before   Optional. The text or HTML to display before the email link.Default empty.
     94 * @param string $after    Optional. The text or HTML to display after the email link. Default empty.
     95 */
     96function comment_author_email_link( $linktext = '', $before = '', $after = '' ) {
    10397    if ( $link = get_comment_author_email_link( $linktext, $before, $after ) )
    10498        echo $link;
    … …  
    114108 * address and use it for their own means good and bad.
    115109 *
     110 * @global object $comment The current Comment row object.
     111 *
    116112 * @since 2.7
    117  * @uses apply_filters() Calls 'comment_email' hook for the display of the comment author's email
    118  * @global object $comment The current Comment row object
    119  *
    120  * @param string $linktext The text to display instead of the comment author's email address
    121  * @param string $before The text or HTML to display before the email link.
    122  * @param string $after The text or HTML to display after the email link.
    123  */
    124 function get_comment_author_email_link($linktext='', $before='', $after='') {
     113 *
     114 * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.
     115 * @param string $before   Optional. The text or HTML to display before the email link. Default empty.
     116 * @param string $after    Optional. The text or HTML to display after the email link. Default empty.
     117 */
     118function get_comment_author_email_link( $linktext = '', $before = '', $after = '' ) {
    125119    global $comment;
    126120    $email = apply_filters('comment_email', $comment->comment_author_email);
    … …  
    144138 * @since 1.5.0
    145139 *
    146  * @param int $comment_ID Optional. The ID of the comment for which to get the author's link.
     140 * @param int $comment_ID Optional. The ID of the comment for which to get the author's link. Default current comment.
    147141 * @return string The comment author name or HTML link for author's URL.
    148142 */
    … …  
    164158 * @see get_comment_author_link() Echoes result
    165159 *
    166  * @param int $comment_ID The ID of the comment for which to print the author's link. Optional.
     160 * @param int $comment_ID Optional. The ID of the comment for which to print the author's link. Default current comment.
    167161 */
    168162function comment_author_link( $comment_ID = 0 ) {
    … …  
    174168 *
    175169 * @since 1.5.0
    176  * @uses $comment
    177  * @uses apply_filters()
    178  *
    179  * @param int $comment_ID The ID of the comment for which to get the author's IP address. Optional.
     170 *
     171 * @param int $comment_ID Optional. The ID of the comment for which to get the author's IP address. Default current comment.
    180172 * @return string The comment author's IP address.
    181173 */
    … …  
    189181 *
    190182 * @since 0.71
    191  * @see get_comment_author_IP() Echoes Result
    192  *
    193  * @param int $comment_ID The ID of the comment for which to print the author's IP address. Optional.
     183 *
     184 * @param int $comment_ID Optional. The ID of the comment for which to print the author's IP address. Default current comment.
    194185 */
    195186function comment_author_IP( $comment_ID = 0 ) {
    … …  
    201192 *
    202193 * @since 1.5.0
    203  * @uses apply_filters() Calls 'get_comment_author_url' hook on the comment author's URL
    204  *
    205  * @param int $comment_ID The ID of the comment for which to get the author's URL. Optional.
     194 *
     195 * @param int $comment_ID Optional. The ID of the comment for which to get the author's URL. Default current comment.
    206196 * @return string
    207197 */
    … …  
    217207 *
    218208 * @since 0.71
    219  * @uses apply_filters()
    220  * @uses get_comment_author_url() Retrieves the comment author's URL
    221  *
    222  * @param int $comment_ID The ID of the comment for which to print the author's URL. Optional.
     209 *
     210 * @param int $comment_ID Optional. The ID of the comment for which to print the author's URL. Default current comment.
    223211 */
    224212function comment_author_url( $comment_ID = 0 ) {
    … …  
    237225 *
    238226 * @since 1.5.0
    239  * @uses apply_filters() Calls the 'get_comment_author_url_link' on the complete HTML before returning.
    240  *
    241  * @param string $linktext The text to display instead of the comment author's email address
    242  * @param string $before The text or HTML to display before the email link.
    243  * @param string $after The text or HTML to display after the email link.
    244  * @return string The HTML link between the $before and $after parameters
     227 *
     228 * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.
     229 * @param string $before   Optional. The text or HTML to display before the email link. Default empty.
     230 * @param string $after    Optional. The text or HTML to display after the email link. Default empty.
     231 * @return string The HTML link between the $before and $after parameters.
    245232 */
    246233function get_comment_author_url_link( $linktext = '', $before = '', $after = '' ) {
    … …  
    259246 *
    260247 * @since 0.71
    261  * @see get_comment_author_url_link() Echoes result
    262  *
    263  * @param string $linktext The text to display instead of the comment author's email address
    264  * @param string $before The text or HTML to display before the email link.
    265  * @param string $after The text or HTML to display after the email link.
     248 *
     249 * @param string $linktext Optional. The text to display instead of the comment author's email address. Default empty.
     250 * @param string $before   Optional. The text or HTML to display before the email link. Default empty.
     251 * @param string $after    Optional. The text or HTML to display after the email link. Default empty.
    266252 */
    267253function comment_author_url_link( $linktext = '', $before = '', $after = '' ) {
    … …  
    274260 * @since 2.7.0
    275261 *
    276  * @param string|array $class One or more classes to add to the class list
    277  * @param int $comment_id An optional comment ID
    278  * @param int $post_id An optional post ID
    279  * @param bool $echo Whether comment_class should echo or return
     262 * @param string|array $class      Optional. One or more classes to add to the class list. Default empty.
     263 * @param int          $comment_id Optional. Comment ID. Default current comment.
     264 * @param int|WP_Post  $post_id    Optional. Post ID or WP_Post object. Default current post.
     265 * @param bool         $echo       Optional. Whether comment_class should echo or return. Default true.
    280266 */
    281267function comment_class( $class = '', $comment_id = null, $post_id = null, $echo = true ) {
    … …  
    293279 * @since 2.7.0
    294280 *
    295  * @param string|array $class One or more classes to add to the class list
    296  * @param int $comment_id An optional comment ID
    297  * @param int $post_id An optional post ID
    298  * @return array Array of classes
     281 * @param string|array $class      Optional. One or more classes to add to the class list. Default empty.
     282 * @param int          $comment_id Optional. Comment ID. Default current comment.
     283 * @param int|WP_Post  $post_id    Optional. Post ID or WP_Post object. Default current post.
     284 * @return array An array of classes.
    299285 */
    300286function get_comment_class( $class = '', $comment_id = null, $post_id = null ) {
    … …  
    364350 *
    365351 * @since 1.5.0
    366  * @uses apply_filters() Calls 'get_comment_date' hook with the formatted date and the $d parameter respectively
    367  * @uses $comment
    368  *
    369  * @param string $d The format of the date (defaults to user's config)
    370  * @param int $comment_ID The ID of the comment for which to get the date. Optional.
    371  * @return string The comment's date
     352 *
     353 * @param string $d          Optional. The format of the date. Default user's setting.
     354 * @param int    $comment_ID Optional. The ID of the comment for which to get the date. Default current comment.
     355 * @return string The comment's date.
    372356 */
    373357function get_comment_date( $d = '', $comment_ID = 0 ) {
    … …  
    385369 * @since 0.71
    386370 *
    387  * @param string $d The format of the date (defaults to user's config)
    388  * @param int $comment_ID The ID of the comment for which to print the date. Optional.
     371 * @param string $d          Optional. The format of the date. Default user's settings.
     372 * @param int    $comment_ID Optional. The ID of the comment for which to print the date. Default current comment.
    389373 */
    390374function comment_date( $d = '', $comment_ID = 0 ) {
    … …  
    400384 *
    401385 * @since 1.5.0
    402  * @uses $comment
    403  * @uses apply_filters() Calls 'get_comment_excerpt' on truncated comment
    404  *
    405  * @param int $comment_ID The ID of the comment for which to get the excerpt. Optional.
    406  * @return string The maybe truncated comment with 20 words or less
     386 *
     387 * @param int $comment_ID Optional. The ID of the comment for which to get the excerpt. Default current comment.
     388 * @return string The maybe truncated comment with 20 words or less.
    407389 */
    408390function get_comment_excerpt( $comment_ID = 0 ) {
    … …  
    429411 *
    430412 * @since 1.2.0
    431  * @uses apply_filters() Calls 'comment_excerpt' hook before displaying excerpt
    432  *
    433  * @param int $comment_ID The ID of the comment for which to print the excerpt. Optional.
     413 *
     414 * @param int $comment_ID Optional. The ID of the comment for which to print the excerpt. Default current comment.
    434415 */
    435416function comment_excerpt( $comment_ID = 0 ) {
    … …  
    441422 *
    442423 * @since 1.5.0
    443  * @uses $comment
    444  * @uses apply_filters() Calls the 'get_comment_ID' hook for the comment ID
    445  *
    446  * @return int The comment ID
     424 *
     425 * @return int The comment ID.
    447426 */
    448427function get_comment_ID() {
    … …  
    452431
    453432/**
    454  * Displays the comment id of the current comment.
     433 * Display the comment id of the current comment.
    455434 *
    456435 * @since 0.71
    457  * @see get_comment_ID() Echoes Result
    458436 */
    459437function comment_ID() {
    … …  
    465443 *
    466444 * @since 1.5.0
    467  * @uses $comment
    468  *
    469  * @param object|string|int $comment Comment to retrieve.
    470  * @param array $args Optional args.
     445 *
     446 * @param mixed $comment Optional. Comment to retrieve. Default current comment.
     447 * @param array $args    Optional. An array of arguments to override the defaults. @see get_page_of_comment()
    471448 * @return string The permalink to the given comment.
    472449 */
    … …  
    510487
    511488/**
    512  * Retrieves the link to the current post comments.
    513  *
    514  * @since 1.5.0
    515  *
    516  * @param int $post_id Optional post id
    517  * @return string The link to the comments
    518  */
    519 function get_comments_link($post_id = 0) {
     489 * Retrieve the link to the current post comments.
     490 *
     491 * @since 1.5.0
     492 *
     493 * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.
     494 * @return string The link to the comments.
     495 */
     496function get_comments_link( $post_id = 0 ) {
    520497    return apply_filters( 'get_comments_link', get_permalink( $post_id ) . '#comments', $post_id );
    521498}
    522499
    523500/**
    524  * Displays the link to the current post comments.
     501 * Display the link to the current post comments.
    525502 *
    526503 * @since 0.71
    527504 *
    528  * @param string $deprecated Not Used
    529  * @param bool $deprecated_2 Not Used
     505 * @param string $deprecated   Not Used.
     506 * @param bool   $deprecated_2 Not Used.
    530507 */
    531508function comments_link( $deprecated = '', $deprecated_2 = '' ) {
    … …  
    541518 *
    542519 * @since 1.5.0
    543  * @uses apply_filters() Calls the 'get_comments_number' hook on the number of comments
    544  *
    545  * @param int $post_id The Post ID
    546  * @return int The number of comments a post has
     520 *
     521 * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.
     522 * @return int The number of comments a post has.
    547523 */
    548524function get_comments_number( $post_id = 0 ) {
    … …  
    565541 *
    566542 * @since 0.71
    567  * @uses apply_filters() Calls the 'comments_number' hook on the output and number of comments respectively.
    568  *
    569  * @param string $zero Text for no comments
    570  * @param string $one Text for one comment
    571  * @param string $more Text for more than one comment
     543 *
     544 * @param string $zero       Optional. Text for no comments. Default false.
     545 * @param string $one        Optional. Text for one comment. Default false.
     546 * @param string $more       Optional. Text for more than one comment. Default false.
    572547 * @param string $deprecated Not used.
    573548 */
    … …  
    593568 * @since 1.5.0
    594569 *
    595  * @param int   $comment_ID Optional. The ID of the comment for which to get the text.
    596  *                          Default 0.
     570 * @param int   $comment_ID Optional. The ID of the comment for which to get the text. Default current comment.
    597571 * @param array $args       Optional. An array of arguments. @see Walker_Comment::comment()
    598  *                          Default empty array.
    599572 * @return string The comment content.
    600573 */
    … …  
    644617 *
    645618 * @since 1.5.0
    646  * @uses $comment
    647  * @uses apply_filter() Calls 'get_comment_time' hook with the formatted time, the $d parameter, and $gmt parameter passed.
    648  *
    649  * @param string $d Optional. The format of the time (defaults to user's config)
    650  * @param bool $gmt Whether to use the GMT date
    651  * @param bool $translate Whether to translate the time (for use in feeds)
     619 *
     620 * @param string $d         Optional. The format of the time. Default user's settings.
     621 * @param bool   $gmt       Optional. Whether to use the GMT date. Default false.
     622 * @param bool   $translate Optional. Whether to translate the time (for use in feeds). Default true.
    652623 * @return string The formatted time
    653624 */
    … …  
    667638 * @since 0.71
    668639 *
    669  * @param string $d Optional. The format of the time (defaults to user's config)
     640 * @param string $d Optional. The format of the time. Default user's settings.
    670641 */
    671642function comment_time( $d = '' ) {
    … …  
    677648 *
    678649 * @since 1.5.0
    679  * @uses $comment
    680  * @uses apply_filters() Calls the 'get_comment_type' hook on the comment type
    681  *
    682  * @param int $comment_ID The ID of the comment for which to get the type. Optional.
     650 *
     651 * @param int $comment_ID Optional. The ID of the comment for which to get the type. Default current comment.
    683652 * @return string The comment type
    684653 */
    … …  
    696665 * @since 0.71
    697666 *
    698  * @param string $commenttxt The string to display for comment type
    699  * @param string $trackbacktxt The string to display for trackback type
    700  * @param string $pingbacktxt The string to display for pingback type
    701  */
    702 function comment_type($commenttxt = false, $trackbacktxt = false, $pingbacktxt = false) {
     667 * @param string $commenttxt   Optional. The string to display for comment type. Default false.
     668 * @param string $trackbacktxt Optional. The string to display for trackback type. Default false.
     669 * @param string $pingbacktxt  Optional. The string to display for pingback type. Default false.
     670 */
     671function comment_type( $commenttxt = false, $trackbacktxt = false, $pingbacktxt = false ) {
    703672    if ( false === $commenttxt ) $commenttxt = _x( 'Comment', 'noun' );
    704673    if ( false === $trackbacktxt ) $trackbacktxt = __( 'Trackback' );
    … …  
    725694 *
    726695 * @since 1.5.0
    727  * @uses apply_filters() Calls 'trackback_url' on the resulting trackback URL
    728  *
    729  * @return string The trackback URL after being filtered
     696 *
     697 * @return string The trackback URL after being filtered.
    730698 */
    731699function get_trackback_url() {
    … …  
    739707
    740708/**
    741  * Displays the current post's trackback URL.
     709 * Display the current post's trackback URL.
    742710 *
    743711 * @since 0.71
    744  * @uses get_trackback_url() Gets the trackback url for the current post
    745  *
    746  * @param bool $deprecated_echo Remove backwards compat in 2.5
     712 *
     713 * @param bool $deprecated_echo Not used.
    747714 * @return void|string Should only be used to echo the trackback URL, use get_trackback_url() for the result instead.
    748715 */
    … …  
    757724
    758725/**
    759  * Generates and displays the RDF for the trackback information of current post.
     726 * Generate and display the RDF for the trackback information of current post.
    760727 *
    761728 * Deprecated in 3.0.0, and restored in 3.0.1.
    … …  
    763730 * @since 0.71
    764731 *
    765  * @param int $deprecated Not used (Was $timezone = 0)
     732 * @param int $deprecated Not used (Was $timezone = 0).
    766733 */
    767734function trackback_rdf( $deprecated = '' ) {
    … …  
    790757 *
    791758 * @since 1.5.0
    792  * @uses $post
    793  *
    794  * @param int $post_id An optional post ID to check instead of the current post.
    795  * @return bool True if the comments are open
     759 *
     760 * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.
     761 * @return bool True if the comments are open.
    796762 */
    797763function comments_open( $post_id = null ) {
    … …  
    807773 *
    808774 * @since 1.5.0
    809  * @uses $post
    810  *
    811  * @param int $post_id An optional post ID to check instead of the current post.
     775 *
     776 * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default current post.
    812777 * @return bool True if pings are accepted
    813778 */
    … …  
    821786
    822787/**
    823  * Displays form token for unfiltered comments.
     788 * Display form token for unfiltered comments.
    824789 *
    825790 * Will only display nonce token if the current user has permissions for
    … …  
    833798 *
    834799 * @since 2.1.3
    835  * @uses $post Gets the ID of the current post for the token
    836800 */
    837801function wp_comment_form_unfiltered_html_nonce() {
    … …  
    846810
    847811/**
    848  * Loads the comment template specified in $file.
     812 * Load the comment template specified in $file.
    849813 *
    850814 * Will not display the comments template if not on single post or page, or if
    … …  
    861825 * halted. It is advised for that reason, that the default theme is not deleted.
    862826 *
    863  * @since 1.5.0
    864  * @global array $comment List of comment objects for the current post
    865  * @uses $wpdb
    866  * @uses $post
     827 * @todo Document globals
    867828 * @uses $withcomments Will not try to get the comments if the post has none.
    868829 *
    869  * @param string $file Optional, default '/comments.php'. The file to load
    870  * @param bool $separate_comments Optional, whether to separate the comments by comment type. Default is false.
    871  * @return null Returns null if no comments appear
     830 * @since 1.5.0
     831 *
     832 * @param string $file              Optional. The file to load. Default '/comments.php'.
     833 * @param bool   $separate_comments Optional. Whether to separate the comments by comment type. Default false.
     834 * @return null Returns null if no comments appear.
    872835 */
    873836function comments_template( $file = '/comments.php', $separate_comments = false ) {
    … …  
    943906
    944907/**
    945  * Displays the JS popup script to show a comment.
     908 * Display the JS popup script to show a comment.
    946909 *
    947910 * If the $file parameter is empty, then the home page is assumed. The defaults
    … …  
    951914 * normal comment link will be assumed.
    952915 *
     916 * @global string $wpcommentspopupfile  The URL to use for the popup window.
     917 * @global int    $wpcommentsjavascript Whether to use JavaScript. Set when function is called.
     918 *
    953919 * @since 0.71
    954  * @global string $wpcommentspopupfile The URL to use for the popup window
    955  * @global int $wpcommentsjavascript Whether to use JavaScript. Set when function is called
    956  *
    957  * @param int $width Optional. The width of the popup window
    958  * @param int $height Optional. The height of the popup window
    959  * @param string $file Optional. Sets the location of the popup window
    960  */
    961 function comments_popup_script($width=400, $height=400, $file='') {
     920 *
     921 * @param int $width  Optional. The width of the popup window. Default 400.
     922 * @param int $height Optional. The height of the popup window. Default 400.
     923 * @param string $file Optional. Sets the location of the popup window.
     924 */
     925function comments_popup_script( $width = 400, $height = 400, $file = '' ) {
    962926    global $wpcommentspopupfile, $wpcommentsjavascript;
    963927
    … …  
    979943 * lists of posts
    980944 *
     945 * @global string $wpcommentspopupfile  The URL to use for the popup window.
     946 * @global int    $wpcommentsjavascript Whether to use JavaScript. Set when function is called.
     947 *
    981948 * @since 0.71
    982  * @uses $wpcommentspopupfile
    983  * @uses $wpcommentsjavascript
    984  * @uses $post
    985  *
    986  * @param string $zero The string to display when no comments
    987  * @param string $one The string to display when only one comment is available
    988  * @param string $more The string to display when there are more than one comment
    989  * @param string $css_class The CSS class to use for comments
    990  * @param string $none The string to display when comments have been turned off
     949 *
     950 * @param string $zero      Optional. The string to display when no comments. Default false.
     951 * @param string $one       Optional. The string to display when only one comment is available. Default false.
     952 * @param string $more      Optional. The string to display when there are more than one comment. Default false.
     953 * @param string $css_class Optional. The CSS class to use for comments. Default empty.
     954 * @param string $none      Optional. The string to display when comments have been turned off. Default false.
    991955 * @return null Returns null on single posts and pages.
    992956 */
    … …  
    10471011 *
    10481012 * @param array $args {
    1049  *     Override default options.
    1050  *
    1051  *     @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.
    1052  *                               Default is 'comment'.
    1053  *     @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.
    1054  *                               Default is 'respond'.
    1055  *     @type string 'reply_text' The text of the Reply link.
    1056  *                               Default is 'Reply'.
    1057  *     @type string 'login_text' The text of the link to reply if logged out.
    1058  *                               Default is 'Log in to Reply'.
    1059  *     @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.
    1060  *                               Default is 0.
    1061  *     @type string 'before'     The text or HTML to add before the reply link.
    1062  *                               Default empty string.
    1063  *     @type string 'after'      The text or HTML to add after the reply link.
    1064  *                               Default empty string.
     1013 *     Optional. Override default arguments.
     1014 *
     1015 *     @type string 'add_below'  The first part of the selector used to identify the comment to respond below. The resulting
     1016 *                               value is passed as the first parameter to addComment.moveForm(), concatenated
     1017 *                               as $add_below-$comment->comment_ID. Default 'comment'.
     1018 *     @type string 'respond_id' The selector identifying the responding comment. Passed as the third parameter to addComment.moveForm(),
     1019 *                               and appended to the link URL as a hash value. Default 'respond'.
     1020 *     @type string 'reply_text' The text of the Reply link. Default 'Reply'.
     1021 *     @type string 'login_text' The text of the link to reply if logged out. Default 'Log in to Reply'.
     1022 *     @type int    'depth'      The depth of the new comment. Must be greater than 0 and less than the value of the 'thread_comments_depth'
     1023 *                               option set in Settings > Discussion.
     1024 *                               Default 0.
     1025 *     @type string 'before'     The text or HTML to add before the reply link. Default empty.
     1026 *     @type string 'after'      The text or HTML to add after the reply link. Default empty.
    10651027 * }
    1066  * @param int $comment Optional. Comment being replied to.
    1067  * @param int $post    Optional. Post that the comment is going to be displayed on.
    1068  * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
     1028 * @param int         $comment Optional. Comment being replied to. Default current comment.
     1029 * @param int|WP_Post $post    Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.
     1030 * @return mixed Link to show comment form, if successful. False, if comments are closed.
    10691031 */
    10701032function get_comment_reply_link($args = array(), $comment = null, $post = null) {
    … …  
    11211083 *
    11221084 * @since 2.7.0
    1123  * @see get_comment_reply_link() Echoes result
    1124  *
    1125  * @param array $args Optional. Override default options, @see get_comment_reply_link().
    1126  * @param int $comment Optional. Comment being replied to.
    1127  * @param int $post Optional. Post that the comment is going to be displayed on.
    1128  * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
     1085 *
     1086 * @param array       $args    Optional. Override default options, @see get_comment_reply_link()
     1087 * @param int         $comment Optional. Comment being replied to. Default current comment.
     1088 * @param int|WP_Post $post    Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.
     1089 * @return mixed Link to show comment form, if successful. False, if comments are closed.
    11291090 */
    11301091function comment_reply_link($args = array(), $comment = null, $post = null) {
    … …  
    11351096 * Retrieve HTML content for reply to post link.
    11361097 *
    1137  * The default arguments that can be override are 'add_below', 'respond_id',
    1138  * 'reply_text', 'login_text', and 'depth'. The 'login_text' argument will be
    1139  * used, if the user must log in or register first before posting a comment. The
    1140  * 'reply_text' will be used, if they can post a reply. The 'add_below' and
    1141  * 'respond_id' arguments are for the JavaScript moveAddCommentForm() function
    1142  * parameters.
    1143  *
    1144  * @todo See get_comment_reply_link() for a template of the args docblock.
    1145  *
    11461098 * @since 2.7.0
    11471099 *
    1148  * @param array $args Optional. Override default options.
    1149  * @param int|object $post Optional. Post that the comment is going to be displayed on. Defaults to current post.
     1100 * @param array $args {
     1101 *     Optional. Override default arguments.
     1102 *
     1103 *     @type string 'add_below'  The first part of the selector used to identify the comment to respond below.
     1104 *                               The resulting value is passed as the first parameter to addComment.moveForm(),
     1105 *                               concatenated as $add_below-$comment->comment_ID. Default is 'post'.
     1106 *     @type string 'respond_id' The selector identifying the responding comment. Passed as the third parameter
     1107 *                               to addComment.moveForm(), and appended to the link URL as a hash value. Default is 'respond'.
     1108 *     @type string 'reply_text' The text of the Reply link. Default is 'Leave a Comment'.
     1109 *     @type string 'login_text' The text of the link to reply if logged out. Default is 'Log in to leave a Comment'.
     1110 *     @type string 'before'     The text or HTML to add before the reply link. Default empty.
     1111 *     @type string 'after'      The text or HTML to add after the reply link. Default empty.
     1112 * }
     1113 * @param int|WP_Post $post    Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.
    11501114 * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
    11511115 */
    … …  
    11801144 * @since 2.7.0
    11811145 *
    1182  * @param array $args Optional. Override default options, @see get_post_reply_link().
    1183  * @param int|object $post Optional. Post that the comment is going to be displayed on.
     1146 * @param array       $args Optional. Override default options, @see get_post_reply_link()
     1147 * @param int|WP_Post $post Optional. Post ID or WP_Post object the comment is going to be displayed on. Default current post.
    11841148 * @return string|bool|null Link to show comment form, if successful. False, if comments are closed.
    11851149 */
    … …  
    11931157 * @since 2.7.0
    11941158 *
    1195  * @param string $text Optional. Text to display for cancel reply link.
    1196  */
    1197 function get_cancel_comment_reply_link($text = '') {
     1159 * @param string $text Optional. Text to display for cancel reply link. Default empty.
     1160 */
     1161function get_cancel_comment_reply_link( $text = '' ) {
    11981162    if ( empty($text) )
    11991163        $text = __('Click here to cancel reply.');
    … …  
    12091173 * @since 2.7.0
    12101174 *
    1211  * @param string $text Optional. Text to display for cancel reply link.
    1212  */
    1213 function cancel_comment_reply_link($text = '') {
     1175 * @param string $text Optional. Text to display for cancel reply link. Default empty.
     1176 */
     1177function cancel_comment_reply_link( $text = '' ) {
    12141178    echo get_cancel_comment_reply_link($text);
    12151179}
    … …  
    12201184 * @since 3.0.0
    12211185 *
     1186 * @param int $id Optional. Post ID. Default current post ID.
    12221187 * @return string Hidden input HTML for replying to comments
    12231188 */
    … …  
    12361201 *
    12371202 * @since 2.7.0
    1238  * @see get_comment_id_fields() Echoes result
     1203 *
     1204 * @param int $id Optional. Post ID. Default current post ID.
    12391205 */
    12401206function comment_id_fields( $id = 0 ) {
    … …  
    12431209
    12441210/**
    1245  * Display text based on comment reply status. Only affects users with Javascript disabled.
     1211 * Display text based on comment reply status.
     1212 *
     1213 * Only affects users with Javascript disabled.
    12461214 *
    12471215 * @since 2.7.0
    12481216 *
    1249  * @param string $noreplytext Optional. Text to display when not replying to a comment.
    1250  * @param string $replytext Optional. Text to display when replying to a comment. Accepts "%s" for the author of the comment being replied to.
    1251  * @param string $linktoparent Optional. Boolean to control making the author's name a link to their comment.
     1217 * @param string $noreplytext  Optional. Text to display when not replying to a comment. Default false.
     1218 * @param string $replytext    Optional. Text to display when replying to a comment.
     1219 *                             Default false. Accepts "%s" for the author of the comment being replied to.
     1220 * @param string $linktoparent Optional. Boolean to control making the author's name a link to their comment. Default true.
    12521221 */
    12531222function comment_form_title( $noreplytext = false, $replytext = false, $linktoparent = true ) {
    … …  
    15371506
    15381507/**
    1539  * List comments
    1540  *
    1541  * Used in the comments.php template to list comments for a particular post
     1508 * List comments.
     1509 *
     1510 * Used in the comments.php template to list comments for a particular post.
    15421511 *
    15431512 * @since 2.7.0
    1544  * @uses Walker_Comment
    1545  *
    1546  * @param string|array $args Formatting options
    1547  * @param array $comments Optional array of comment objects. Defaults to $wp_query->comments
    1548  */
    1549 function wp_list_comments($args = array(), $comments = null ) {
     1513 *
     1514 * @param string|array $args {
     1515 *     Optional. Formatting options.
     1516 *
     1517 *     @type string 'walker'            The Walker class used to list comments. Default null.
     1518 *     @type int    'max_depth'         The maximum comments depth. Default empty.
     1519 *     @type string 'style'             The style of list ordering. Default 'ul'. Accepts 'ul', 'ol'.
     1520 *     @type string 'callback'          Callback function to use. Default null.
     1521 *     @type string 'end-callback'      Callback function to use at the end. Default null.
     1522 *     @type string 'type'              Type of comments to list.
     1523 *                                      Default 'all'. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'.
     1524 *     @type int    'page'              Page ID to list comments for. Default empty.
     1525 *     @type int    'per_page'          Number of comments to list per page. Default empty.
     1526 *     @type int    'avatar_size'       Height and width dimensions of the avatar size. Default 32.
     1527 *     @type string 'reverse_top_level' Ordering of the listed comments. Default null. Accepts 'desc', 'asc'.
     1528 *     @type bool   'reverse_children'  Whether to reverse child comments in the list. Default null.
     1529 *     @type string 'format'            How to format the comments list.
     1530 *                                      Default 'html5' if the theme supports it. Accepts 'html5', 'xhtml'.
     1531 *     @type bool   'short_ping'        Whether to output short pings. Default false.
     1532 * }
     1533 * @param array $comments Optional. Array of comment objects. @see WP_Query->comments
     1534 */
     1535function wp_list_comments( $args = array(), $comments = null ) {
    15501536    global $wp_query, $comment_alt, $comment_depth, $comment_thread_alt, $overridden_cpage, $in_comment_loop;
    15511537
    … …  
    16441630
    16451631/**
    1646  * Outputs a complete commenting form for use within a template.
     1632 * Output a complete commenting form for use within a template.
     1633 *
    16471634 * Most strings and form fields may be controlled through the $args array passed
    16481635 * into the function, while you may also choose to use the comment_form_default_fields
    … …  
    16531640 *
    16541641 * @since 3.0.0
    1655  * @param array $args Options for strings, fields etc in the form
    1656  * @param mixed $post_id Post ID to generate the form for, uses the current post if null
    1657  * @return void
     1642 *
     1643 * @todo Fully document $args
     1644 * @param array       $args    Optional. Options for strings, fields etc. in the form.
     1645 * @param int|WP_Post $post_id Optional. Post ID or WP_Post object to generate the form for. Default current post.
    16581646 */
    16591647function comment_form( $args = array(), $post_id = null ) {
Note: See TracChangeset for help on using the changeset viewer.