Opened 5 years ago

Closed 5 years ago

#4201 closed defect (bug) (wontfix)

Function description is incomplete.

Reported by: jankimoradiya's profile jankimoradiya Owned by:
Milestone: Priority: normal
Component: General Keywords: needs-patch


"request" function description is incomplete. @param & @return are missing in "public function request" function of public_html/trunk/ file.

Attachments (2)

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

Download all attachments as: .zip

Change History (6)

5 years ago

#1 @jankimoradiya
5 years ago

Hello Team,

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


#2 @Otto42
5 years ago

  • Component changed from to General

5 years ago

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

5 years ago

#4 @dd32
5 years 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

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.