WordPress.org

Making WordPress.org

Opened 5 months ago

Closed 4 months ago

#4201 closed defect (wontfix)

Function description is incomplete.

Reported by: jankimoradiya Owned by:
Milestone: Priority: normal
Component: General Keywords: needs-patch
Cc:

Description

"request" function description is incomplete. @param & @return are missing in "public function request" function of public_html/trunk/wordpress.org/public_html/wp-content/mu-plugins/pub/wporg-page-limiter.php file.

Attachments (2)

00000.diff (677 bytes) - added by jankimoradiya 5 months ago.
#4201.diff (677 bytes) - added by jankimoradiya 5 months ago.

Download all attachments as: .zip

Change History (6)

@jankimoradiya
5 months ago

#1 @jankimoradiya
5 months ago

Hello Team,

I have attached above patch to added @param & @return in description in "public function request" function.

Thanks

#2 @Otto42
5 months ago

  • Component changed from learn.wordpress.org to General

@jankimoradiya
5 months ago

This ticket was mentioned in Slack in #meta by jankimoradiya. View the logs.


4 months ago

#4 @dd32
4 months ago

  • Keywords needs-patch added; has-patch removed
  • Resolution set to wontfix
  • Status changed from new to closed

@jankimoradiya If you’re going to submit documentation patches like that, can you please complete the entire file instead of singular functions?

I’m no longer going to commit documentation patches which add no overall benefit, such as this one, and instead just close the ticket. In the past I've committed them and moved on, as it was quicker to commit than to write a comment such as this.

The addition of PHPDoc syntax for a single method and Configuration arguments. adds zero benefit to the code, and if anything only makes the file less consistent with itself and the rest of WordPress.org.

I don’t see any point in ‘improving’ the function comments in that file, primarily as they're short methods which are easily readable by a developer (and not intended on being used by others widely), but if you’re willing to go to the effort then sure.

To be an accepted patch, IMHO it should not only convert it to a PHPDoc syntax, but properly document all arguments and return values. The documentation should be complete enough that someone wouldn't need to read the code to understand what the method is going to be doing.

I'm closing this ticket as suggested for now, but if you do patch it with the above in mind, please feel free to re-open it.

Note: See TracTickets for help on using tickets.