[wp-trac] [WordPress Trac] #44224: Missing @return in Doc comment

[WordPress Trac]

#44224: Missing @return in Doc comment
-------------------------------------------------+-------------------------
 Reporter:  subrataemfluence                     |       Owner:
                                                 |  subrataemfluence
     Type:  defect (bug)                         |      Status:  assigned
 Priority:  normal                               |   Milestone:  5.1
Component:  Plugins                              |     Version:  trunk
 Severity:  normal                               |  Resolution:
 Keywords:  has-patch good-first-bug needs-      |     Focuses:  docs
  refresh                                        |
-------------------------------------------------+-------------------------
Changes (by desrosj):

 * keywords:  has-patch good-first-bug commit => has-patch good-first-bug
     needs-refresh
 * milestone:  5.0.3 => 5.1


Comment:

 Moving this to 5.1.

 One more nit. I think `Required.` is implied when there is no default
 value specified for a parameter, so I don't think we need that.

 I looked through core and only found a handful of `@param` tags with
 `Required.`. They seem to fall into a few scenarios:

 - The parameter has a default value specified.
 - It is a required parameter within an array and others are optional
 (Although the handbook seems to favor marking the optional parameters
 instead).
 - Parameters that are required, but may have scenarios that call for
 falsey/empty values to be passed.
 - Functions where there are a mix of optional and required parameters.

 Clarifying appropriate use of `Required.` in the
 [https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/php/ documentation handbook] may be helpful.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/44224#comment:10>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform