[wp-meta] [Making WordPress.org] #4201: Function description is incomplete.

[Making WordPress.org]

#4201: Function description is incomplete.
---------------------------+----------------------
 Reporter:  jankimoradiya  |       Owner:  (none)
     Type:  defect         |      Status:  closed
 Priority:  normal         |   Milestone:
Component:  General        |  Resolution:  wontfix
 Keywords:  needs-patch    |
---------------------------+----------------------
Changes (by dd32):

 * keywords:  has-patch => needs-patch
 * status:  new => closed
 * resolution:   => wontfix


Comment:

 @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.

-- 
Ticket URL: <https://meta.trac.wordpress.org/ticket/4201#comment:4>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org