Parser doesn't recognize line breaks and/or lists

[samuelsidler]

Note here: ​http://developer.wordpress.org/reference/function/wp_insert_post/

That page should display something closer to this:

The defaults for the parameter $postarr are:
    'post_status'   - Default is 'draft'.
    'post_type'     - Default is 'post'.
    'post_author'   - Default is current user ID ($user_ID). The ID of the user who added the post.
    'ping_status'   - Default is the value in 'default_ping_status' option.
                      Whether the attachment can accept pings.
    'post_parent'   - Default is 0. Set this for the post it belongs to, if any.
    'menu_order'    - Default is 0. The order it is displayed.
    'to_ping'       - Whether to ping.
    'pinged'        - Default is empty string.
    'post_password' - Default is empty string. The password to access the attachment.
    'guid'          - Global Unique ID for referencing the attachment.
    'post_content_filtered' - Post content filtered.
    'post_excerpt'  - Post excerpt.

That is, there should be line breaks for each line and they should be formatted well. This might be a parser issue or something the plugin/theme can fix.

[samuelsidler]

This is going to be an issue between the parser and inline documentation. If we put HTML in the inline docs (as in, formatting HTML not HTML used in examples), it will cause problems when we need to use HTML in the examples. If we use plain text all around, we'll have issues because we can't do lists and other similar things.

Perhaps we need to use markdown across all inline docs? Drew, what do you think we should be doing here?

Parsing line breaks isn't the right answer, per Rarst. We'll have problems later in other scenarios.

[rzen]

I'd wager this issue is entirely one of output, not of parsing, but I'm not sure if that's controlled by the theme or plugin. If I modify the markup using Chrome's inspector, converting the <p> tag to a <pre> tag, we get a nicely formatted block of documentation:

Unrelated to the output, the content we're outputting here should actually be written in ​hash notation.

[kpdesign]

I've talked with @Rarst about this issue a couple times, and the standard has been amended to include guidelines that should take care of most of these issues: ​Formatting Guidelines.

I will continue to work with @Rarst on this, as needed, should other issues arise.

[nicole@…]

I've looked into fixing this on the front end, and while <pre> does fix the spacing issue, the results are less than desired.

Ultimately, this needs to be fixed from the back end. The parser needs to parse param array values in the docblock, and searching through the code (keep in mind, I'm not familiar with the intricacies of the parser) I see that there is a getParsedDescription() function in vendor/phpdocumentor/reflection-docblock/src/phpDocumentor/Reflection/DocBlock/Tag.php on line 297 that appears to do just that. Line 131 of lib/runner.php uses getDescription(), which is defined in that same Tag.php file on line 270.

So my thought is that the runner.php code is getting the tag description before it is parsed and it should be getting a parsed version of the tag description instead. If my thinking is correct, this should give us a multidimensional array providing the nested tags as separate objects that we can then properly output in the theme.

I may be way off the mark, but thoughts?

[coffee2code]

Formatting of parsed content in general should be much improved now.

Previously linebreaks in parsed docs would be translated to <br>, causing the text to be unnecessarily narrow in the Code Ref. This was fixed on the parser side of things (see ​1, ​2).

The specifically referenced issue in the ticket has been indirectly addressed globally. The WP 4.0 release included a docs initiative to document params that accept a keyed array argument(s) (e.g. the $postarr from the ticket-referenced function). Part of that effort was to move such existing argument documentation into the more appropriate Parameters section and document it according to a more rigorous guideline.

Granted, in so doing, the introduction of the new parameter notation means the parser doesn't parse the hash for its requisite parts (it's just a run-on string for now) which meant its unaffected display was also be a run-on block of text. A temporary solution has been implemented (which can do with some iteration), but we'll have to address this in both the parser and theme before long.