Parse array parameter docs

[smckeown]

Some of the parameter docs use lists. Markdown needs to be parsed in parameter docs.

See this for reference: https://meta.trac.wordpress.org/ticket/197

[Rarst]

Actually the parameters are not markdown list, but more of a case of special formatting. Not sure what is it based on / called properly. :)

 * @param array $postarr {
 *     An array of elements that make up a post to update or insert.
 *
 *     @type int    $ID                    The post ID. If equal to something other than 0, the post with that ID will
 *                                         be updated. Default 0.
 *     @type string $post_status           The post status. Default 'draft'.
 *     @type string $post_type             The post type. Default 'post'.
 *     @type int    $post_author           The ID of the user who added the post. Default the current user ID.
 *     @type bool   $ping_status           Whether the post can accept pings. Default value of 'default_ping_status' option.
 *     @type int    $post_parent           Set this for the post it belongs to, if any. Default 0.
 *     @type int    $menu_order            The order it is displayed. Default 0.
 *     @type string $to_ping               Space or carriage return-separated list of URLs to ping. Default empty string.
 *     @type string $pinged                Space or carriage return-separated list of URLs that have been pinged.
 *                                         Default empty string.
 *     @type string $post_password         The password to access the post. Default empty string.
 *     @type string $guid'                 Global Unique ID for referencing the post.
 *     @type string $post_content_filtered The filtered post content. Default empty string.
 *     @type string $post_excerpt          The post excerpt. Default empty string.
 * }

[JDGrimes]

This is the way that hashes are described in PHPDoc PSR-5: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-describing-hashes

I’m not sure if PHPDocumentor can parse this out yet or not. Worth investigating.

[DrewAPicture]

It can't. I talked briefly about it with @mvriel (phpDoc maintainer). I talked to the guy from hookr.io at wcnyc about parsing hash notations and he mentioned he might have some code that he could contribute.

[mvriel]

Hi @DrewAPicture, you are right; phpDocumentor currently does not yet support this construct because PSR-5 is still in draft and under discussion. Adding that feature would be a bit premature and take time to improve the way phpDocumentor is and the feature requests that are still waiting in queue

[Rarst]

So, should we wait on it for DevHub? Is there estimate for PSR-5 finalization (thinking aloud, I will go look myself tomorrow, about to go off for the night) ?

PS I am very not used to WP being too early for PHP stuff :D

[mvriel]

I think that it would be good to wait for such changes until the PSR is at least less in flux. For example, only two or three weeks ago we had to scrap the plan to deprecate @var in favor of @type because it proved to cause more issues than it solved.

There is no timetable set; I try to regularly write missing chapters or finalize discussions but work on phpDocumentor comes first and my personal life before that even :) (though my wife might feel otherwise sometimes)

[DrewAPicture]

The changes are already in place in core right now. And while we absolutely wish to follow the standard (proposed or not) as closely as possible going forward, we have (and have had for some time) a demonstrated need for documenting default arguments in this way. The fact that the change is proposed at all is a step in the right direction, I think we can all agree on that.

It's also entirely understandable that the hashes/hash notation section of the spec is not yet a top priority for you guys (@mvriel et al), though you should understand that it is one of ours. And thus, waiting an indeterminate amount of time for a decision to be made is holding up the show on our end.

Please don't misunderstand, this is not a call to "please make this your priority". This is me saying, "we have this need and I'd like to explore our options", nothing more. Obviously, any code resulting from these explorations is going to be open source, and would certainly be up for contribution to phpDocumentor should we figure out a good way to do it.

And later, if what comes out of the PSR-5 is demonstrably different in syntax, we can tackle that when we get there. Having to change inline docs and how they're formatted is a way of life in WordPress core.

[johnbillion]

Looks like this was fixed at some point, but I'm not sure where, and I can't see any test coverage for it.

Is there some post-processing happening on developer.wordpress.org? For example, wp_list_comments() has hash notation for its $args parameter, yet it's displayed correctly.

[Rarst]

I... don't remember. :) Production reference does run some hacks (I had never seen myself) on top of Parser, but I doubt it's anything as extensive as dealing with those lists. A little busy with other things right now to de-dust my Parser setup and test.

[DrewAPicture]

@johnbillion @Rarst: Yes, there's still some text processing going on on the front-end to give it halfway decent formatting.

See param_formatting_fixup() in /inc/template-tags.php.

cc @coffee2code