PHPDoc updates for wp-includes/comment-template.php

[DrewAPicture]

This ticket is a followup to #20495. Patch attached.

[DrewAPicture]

All the docs + standards

[DrewAPicture]

In 27156:

Inline documentation cleanup in wp-includes/comment-template.php.

This cleanup follows [25567] and brings the docs in-line with standards that at the time had not yet been finalized.

These changes include

• Moving in-line @see tags to their own lines
• Using docs-specific variables in hook docs
• Fixing line-wrapping throughout
• Typos and punctuation
• Converting hash notation values to variables per the standard

Fixes #27083. See #20495.

[DrewAPicture]

In 27157:

Fix a typo in the PHPDoc for comment_author_email_link().

See #27083.

[SergeyBiryukov]

$end-callback looks weird as a PHP variable due to the hyphen. My initial thought was to change it to $end_callback, however 'end-callback' is the actual value used in Walker_Comment::end_el():
tags/3.8.1/src/wp-includes/comment-template.php#L1660​

Do we need for all string parameters to look like PHP variables?

[DrewAPicture]

Replying to SergeyBiryukov:

$end-callback looks weird as a PHP variable due to the hyphen.
<snip>
Do we need for all string parameters to look like PHP variables?

All arguments in a hash notation need to be expressed as variables per the standard.

However, I don't think we necessarily need to keep the hyphen for the purposes of the docs -- I don't have a problem with changing it to an underscore there.

[SergeyBiryukov]

Replying to DrewAPicture:

All arguments in a hash notation need to be expressed as variables per the standard.

I see, thanks for clarifying that.

However, I don't think we necessarily need to keep the hyphen for the purposes of the docs -- I don't have a problem with changing it to an underscore there.

I think that might cause a confusion with someone trying to pass 'end_callback' instead of 'end-callback' and wondering why it doesn't work. Could we perhaps add some kind of a comment there, like 27083.2.diff​?

[DrewAPicture]

Replying to SergeyBiryukov:

I think that might cause a confusion with someone trying to pass 'end_callback' instead of 'end-callback' and wondering why it doesn't work. Could we perhaps add some kind of a comment there, like 27083.2.diff​?

I think at a certain point, this becomes an exercise in futility :) I'm thinking we should just leave the hyphen in, rather than modify it here and make a note about why it was modified over there, etc. Seems like overkill.

[SergeyBiryukov]

After reading more about ​hash notation, I see that although variable names require the $ sign, it does not mean they're supposed to be interpreted as PHP variables. So I'm fine with [27156] as is, sorry for the confusion.