Function description is incomplete.

[jankimoradiya]

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

[jankimoradiya]

Hello Team,

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

Thanks

[dd32]

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