Make WordPress Core

Opened 18 months ago

Closed 17 months ago

Last modified 17 months ago

#56843 closed defect (bug) (fixed)

Comments in wp-login.php start with an "*" too few.

Reported by: nekojonez's profile NekoJonez Owned by: sergeybiryukov's profile SergeyBiryukov
Milestone: 6.2 Priority: normal
Severity: minor Version:
Component: Login and Registration Keywords: has-patch
Focuses: docs Cc:

Description (last modified by sabernhardt)

On line 98, 427, 537 the comment block starts with /* while all others start with /**.

Change History (8)

This ticket was mentioned in PR #3484 on WordPress/wordpress-develop by @NekoJonez.


18 months ago
#1

  • Keywords has-patch added

This PR would fix trac ticket:
https://core.trac.wordpress.org/ticket/56843

This PR just adds an additional "*" at the start of the comment blocks so it's like all the other ones.

#2 @SergeyBiryukov
18 months ago

Hi there, thanks for the ticket!

I believe the current format is correct here as per the PHP Documentation Standards:

  • /** is reserved for DocBlocks, for example:
    /**
     * Summary.
     *
     * @since x.x.x
     * @var type $var Description.
     */
    
  • /* is for regular multi-line comments:
    /*
     * This is a comment that is long enough to warrant being stretched over
     * the span of multiple lines. You'll notice this follows basically
     * the same format as the PHPDoc wrapping and comment block style.
     */
    

#3 @NekoJonez
18 months ago

@SergeyBiryukov Am I then correct in understanding that my changes aren't needed?

Personally, I find it strange to have a difference between them. But that might be just me.

#4 @sabernhardt
17 months ago

  • Component changed from Comments to Login and Registration
  • Description modified (diff)
  • Focuses docs added

#5 follow-up: @sabernhardt
17 months ago

  • Keywords 2nd-opinion added

I do not think a change is necessary.

However, the "Main part" comment is technically only one line with the multi-line formatting (probably purposely calling attention to how the section is different from the functions preceding it). Maybe the comment would be worth splitting into two lines:

 /*
  * Main part:
  * Check the request and redirect or display a form based on the current action.
  */

#6 in reply to: ↑ 5 @SergeyBiryukov
17 months ago

  • Keywords 2nd-opinion removed
  • Milestone changed from Awaiting Review to 6.2

Replying to sabernhardt:

Maybe the comment would be worth splitting into two lines:

 /*
  * Main part:
  * Check the request and redirect or display a form based on the current action.
  */

Sounds good, thanks!

#7 @SergeyBiryukov
17 months ago

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

In 54848:

Docs: Split the "main part" comment in wp-login.php into two lines.

This aims to better match the multi-line comment format of the documentation standards.

Follow-up to [6643], [52945], [53313].

Props sabernhardt, NekoJonez.
Fixes #56843.

@NekoJonez commented on PR #3484:


17 months ago
#8

Due to the convo on Trac, this is going to be closed.

Note: See TracTickets for help on using tickets.