[wp-trac] [WordPress Trac] #26185: PHPDoc updates for /wp-includes/functions.php

[WordPress Trac]

#26185: PHPDoc updates for /wp-includes/functions.php
----------------------------+------------------------------
 Reporter:  morganestes     |       Owner:
     Type:  defect (bug)    |      Status:  new
 Priority:  normal          |   Milestone:  Awaiting Review
Component:  Bootstrap/Load  |     Version:  3.7
 Severity:  normal          |  Resolution:
 Keywords:  needs-patch     |     Focuses:  docs
----------------------------+------------------------------
Changes (by DrewAPicture):

 * keywords:  has-patch 2nd-opinion => needs-patch


Comment:

 Ideally, I'd like to avoid these huge patches in the future, instead
 focusing on specific change. It's tough to follow what's being changed and
 why, etc.

 That said, here are some notes on [attachment:26185.1.diff]:

 Reference: [http://make.wordpress.org/core/handbook/inline-documentation-
 standards/php-documentation-standards/ Inline Documentation Standards]

 * There should always be a new blank line between the short and long
 descriptions in a doc block
 * If you're going to add parameter descriptions, great. I'd prefer it if
 you consistently space-aligned the parts for parameters. Case in point,
 compare your docs changes for `date_i18n()` vs `deprecated_file()`. The
 style used with `date_i18n()` is definitely preferred :)
 * Please avoid adding new `@global` tags
 * `@link`, `@see`, etc. tags should always fall below the `@since`
 * If parameter description is wrapped, align with the first character of
 the first line with spaces
 * For hash notations (arrays), use a 4-space indent for each level of the
 array, not tabs

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