[wp-trac] [WordPress Trac] #30315: Improve inline documentation of widgets API

[WordPress Trac]

#30315: Improve inline documentation of widgets API
--------------------------+-----------------------------
 Reporter:  ericlewis     |       Owner:
     Type:  defect (bug)  |      Status:  new
 Priority:  normal        |   Milestone:  Future Release
Component:  Widgets       |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  has-patch     |     Focuses:  docs
--------------------------+-----------------------------

Comment (by DrewAPicture):

 Hi Ben, thanks for the patches.

 Please refer to the [https://make.wordpress.org/core/handbook/inline-
 documentation-standards/php-documentation-standards/#1-1-parameters-that-
 are-arrays Parameters that are arrays] section of the standard for a
 refresher on the syntax for hash notations. The example provided there is
 meant to be used as an exact guide for what's expected.

 [attachment:30315.2.diff]:
 * The inner hash notation should only be indented four spaces
 * Descriptions including the hash description should ''always'' end with a
 period. They're very literally sentences

 [attachment:30315.3.diff]:
 * There should be a blank line between the summary and description
 * Parameter and return descriptions should always end with a period
 * The return type should be `int` and there should be a description (with
 a period)

 [attachment:30315.4.diff]:
 * The hash notation should begin with a description, followed by a blank
 line, followed by the `@type` lines
 * Each `@type` line should only be indented four spaces
 * The types and descriptions should be left-aligned with each other
 * The descriptions should mention what type of values are accepted and
 what the defaults are.

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