WordPress.org

Make WordPress Core

Opened 6 years ago

Closed 6 years ago

#27083 closed defect (bug) (fixed)

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

Reported by: DrewAPicture Owned by: DrewAPicture
Milestone: 3.9 Priority: normal
Severity: normal Version:
Component: Comments Keywords: has-patch
Focuses: docs Cc:

Description

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

Attachments (2)

27083.diff (45.7 KB) - added by DrewAPicture 6 years ago.
All the docs + standards
27083.2.diff (1.0 KB) - added by SergeyBiryukov 6 years ago.

Download all attachments as: .zip

Change History (9)

@DrewAPicture
6 years ago

All the docs + standards

#1 @DrewAPicture
6 years ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

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.

#2 @DrewAPicture
6 years ago

In 27157:

Fix a typo in the PHPDoc for comment_author_email_link().

See #27083.

#3 follow-up: @SergeyBiryukov
6 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

$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?

#4 in reply to: ↑ 3 ; follow-up: @DrewAPicture
6 years ago

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.

#5 in reply to: ↑ 4 ; follow-up: @SergeyBiryukov
6 years ago

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?

#6 in reply to: ↑ 5 @DrewAPicture
6 years ago

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.

#7 @SergeyBiryukov
6 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

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.

Note: See TracTickets for help on using tickets.