[wp-trac] [WordPress Trac] #41756: Document arrays of a known type as such

[WordPress Trac]

#41756: Document arrays of a known type as such
----------------------------------+------------------------------
 Reporter:  johnbillion           |       Owner:
     Type:  enhancement           |      Status:  new
 Priority:  low                   |   Milestone:  Awaiting Review
Component:  General               |     Version:
 Severity:  normal                |  Resolution:
 Keywords:  ongoing dev-feedback  |     Focuses:  docs
----------------------------------+------------------------------

Comment (by GaryJ):

 Documenting my process, so others can verify.

 1. Checkout https://github.com/WordPress/phpdoc-parser.git into the
 plugins directory of a fresh WP install.
 2. Active plugin - need PHP 5.4 or later. Open PRs suggest may be issues
 with running PHP 7.0.
 3. Pulled down theme: `svn checkout
 https://meta.svn.wordpress.org/sites/trunk/wordpress.org/public_html/wp-
 content/themes/pub/wporg-developer/ wp-content/themes/wporg-developer`
 4. Activated theme, and replaced references to `WPORGPATH` files with
 header and footer markup from Twenty Seventeen theme.
 5. Ran `wp parser create wp-admin/includes/bookmark.php --user=admin` -
 file chosen as it was one of the files in the patch.
 6. Front end rendered as:
 [[Image(/raw-attachment/ticket/41756/front-end-render-before.png)]]
 Note that `$link_categories` is an `(array)`.
 7. Manually changed the docs for `wp_set_link_cats()` as per patch.
 8. Front end now rendered as:
 [[Image(/raw-attachment/ticket/41756/front-end-render-after.png)]]
 Note that `$link_categories` is an `(int[])`.
 9. Realised you wanted the JSON file. Ran `wp parser export wp-
 admin/includes/bookmark.php --user=admin`
 10. Ran `cat phpdoc.json` and relevant JSON section is:
 {{{
 {
     "name": "param",
     "content": "Array of link category IDs to add the link to.",
     "types": [
         "int[]"
     ],
     "variable": "$link_categories"
 }
 }}}
 [[Image(/raw-attachment/ticket/41756/wp_set_link_cats.png)]]

 11. Repeated for an `array` in `bulk_post_updated_messages` filter hook,
 and got an equivalant result:
 [[Image(/raw-attachment/ticket/41756/bulk_post_updated_messages-
 param.png)]]

 12. Repeated with `@param string|array $body_classes` from
 `setup_config_display_header()`, but changed it to `string|string[]`.
 Resulted in:

 {{{
 {
     "name": "param",
     "content": "",
     "types": [
         "string",
         "string[]"
     ],
     "variable": "$body_classes"
 }

 }}}

 13. Just for fun, repeated 12. but with `string|foobar[]`. Resulted in:
 {{{
 {
     "name": "param",
     "content": "",
     "types": [
         "string",
         "\\foobar[]"
     ],
     "variable": "$body_classes"
 }
 }}}

 14. Tried the exotic format in the OP, on
 `wp_generate_attachment_metadata` filter. Result:
 {{{
 {
     "name": "param",
     "content": "An array of attachment meta data.",
     "types": [
         "\\(int",
         "\\string)[]"
     ],
     "variable": "$metadata"
 },
 }}}

 Conclusion

 - The basic alternative format seems to be accepted without throwing
 errors.
 - The exotic format ([https://github.com/php-fig/fig-
 standards/blob/master/proposed/phpdoc.md#abnf array-expression]) seems to
 be thrown off by the non-recognised / non-valid keywords ("foobar", or
 exactly "(int" or exactly "string)[]").

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