Markdown in descriptions: MUST vs. RECOMMENDED
dharkness opened this issue · comments
Section 5.2 states that tools are RECOMMENDED to support Markdown in the description of a "Structural Element", but section 5.3 states that tools MUST support Markdown for tag descriptions.
- Why the difference?
- If anything, the top-level description is where I'm much more likely to utilize MD support.
Actually, I think I'd prefer to remove both mentions, thus leaving it as an implementation details of applications. I'd rather the spec just not go there if we can help it.
Ping @ondrejmirtes @muglug @neuro159 @mindplay-dk @GaryJones @mvriel @jaapio for opinions.
I think it has some value - otherwise a codebase that happens to use Markdown, or HTML for DocBlocks, may not work smoothly with different parsers.
IMO the less formatting is in description the better...
Anyway IDE will have to gracefully handle all that's out there for years...
On one hand having a spec now shapes the future trend - less html, more md.
On the other hand MD kinda was made to degrade gracefully when viewed as plain text - thus REQUIRED sounds bit too much.
I'll ask my team may be we have stronger opinion)
Well "RECOMMENDED" is the consensus on our end.
On the other hand MD kinda was made to degrade gracefully when viewed as plain text - thus REQUIRED sounds bit too much.
MD will degrade gracefully if it is viewed as plain text, but this is not what is usually happens. For example, PhpStorm does not support MD and does not respect new lines in properties description, so this:
/**
* @var array the rules for creating and parsing URLs when [[enablePrettyUrl]] is `true`.
* This property is used only if [[enablePrettyUrl]] is `true`. Each element in the array
* is the configuration array for creating a single URL rule. The configuration will
* be merged with [[ruleConfig]] first before it is used for creating the rule object.
*
* A special shortcut format can be used if a rule only specifies [[UrlRule::pattern|pattern]]
* and [[UrlRule::route|route]]: `'pattern' => 'route'`. That is, instead of using a configuration
* array, one can use the key to represent the pattern and the value the corresponding route.
* For example, `'post/<id:\d+>' => 'post/view'`.
*
* For RESTful routing the mentioned shortcut format also allows you to specify the
* [[UrlRule::verb|HTTP verb]] that the rule should apply for.
* You can do that by prepending it to the pattern, separated by space.
* For example, `'PUT post/<id:\d+>' => 'post/update'`.
* You may specify multiple verbs by separating them with comma
* like this: `'POST,PUT post/index' => 'post/create'`.
* The supported verbs in the shortcut format are: GET, HEAD, POST, PUT, PATCH and DELETE.
* Note that [[UrlRule::mode|mode]] will be set to PARSING_ONLY when specifying verb in this way
* so you normally would not specify a verb for normal GET request.
*
* Here is an example configuration for RESTful CRUD controller:
*
* ```php
* [
* 'dashboard' => 'site/index',
*
* 'POST <controller:[\w-]+>s' => '<controller>/create',
* '<controller:[\w-]+>s' => '<controller>/index',
*
* 'PUT <controller:[\w-]+>/<id:\d+>' => '<controller>/update',
* 'DELETE <controller:[\w-]+>/<id:\d+>' => '<controller>/delete',
* '<controller:[\w-]+>/<id:\d+>' => '<controller>/view',
* ];
* ```
*
* Note that if you modify this property after the UrlManager object is created, make sure
* you populate the array with rule objects instead of rule configurations.
*/
Would be rendered like this with markdown support:
And rendered like this with "no standard - MD is only a recommendation":
So if MD support is optional, then at least should be some requirement which will avoid degradation of plain text formatting.
PhpStorm does support markdown in top descriptions since 2015 - and I just made it work for tag value (case above) for next week EAP build :)
As to those [[links]] SEMANTICS HAVE TO BE PROPERLY DOCUMENTED - separately!
Is there a specific Markdown specification that we want to go with?
I don't think so/most minimal - we HAVE to support only basic structure like example above + those links.
I found one major contradiction in MD support vs actual phpdoc practices out there:
/**
* This is a sample function to illustrate additional PHP
* formatter options.
* @param $one The first parameter
* @param int $two The second parameter
* @param string $three The third parameter with a longer
* comment to illustrate wrapping.
* @return void
*/
function foo(){}Pay attention to string $three - it is a HIGHLY USED and very REQUESTED IN FORMATTER - wrap and align tag descriptions.
Now BEFORE I added MD in tag desc - rendering was OK. but WITH MD - it detects those (4+) spaces as PREFORMATTED section. We can try to employ some heuristics but... usually its very bad experience for 50% if ppl.
Here is a screenshot of my testdata
How to gracefully handle (==describe in specification & implement) this contradiction?
I think it might depend on the choices that the markdown implementation takes - I haven't read the original markdown spec, though.
This is an example
with github flavored markdown
This is an example
with github flavored markdown
As for heuristics, I'd suggest removing the largest prefix of whitespace which is common in the range of lines from the 2nd line (after removing the first *) until the last line of text associated with a tag such as @param. This would be helpful in cases such as the following
- This should account for both tabs and spaces
/**
* @param string the total number
* of rows.
*
* 1. This is a list in markdown,
* with multiple lines...
*/Then the markdown implementation would process the following as an input:
the total number
of rows
1. This is a list in markdown,
with multiple lines...it is a HIGHLY USED and very REQUESTED IN FORMATTER - wrap and align tag descriptions.
However, I don't think that the requirements for how it's displayed in an IDE (often fixed-width characters, maybe with a line limit), can be assumed to be the same as when that content is extracted and shown when converted to HTML, or otherwise in a different context - whitespace can be normalized for then.
Can we leave the spec such that parsers MAY align wrapped descriptions (including the @param and @return descriptions) with the starting column of that description?
If I could have my way: deprecate inline tags altogether and use markdown instead.
I know it's not likely to happen for legacy reasons, but... every developer in the world uses markdown, everywhere, every day, all day.
So, to be realistic, I think we should say "MAY use Markdown, HTML or any other markup" for tag-descriptions.
I also think we should expand it to cover both the summary text and descriptions in all tags that support them. (e.g. allowed in summary body as well as in e.g. @param descriptions etc.)
I don't think we should recommend or mandate anything from documentation generators - what they do or don't offer should be up to them.
Key benefit of the inline tags is that the docgenerator/IDE can do the resolution of paths to other structural elements. I don't think Markdown URLs alone can be relied on for that.
@ashnazg yeah, my mind started going there... probably a separate PSR would be needed for "Markdown in PhpDoc", which would define additional features like URLs, @ mentions, code spans/blocks, etc. - completely out of scope for this PSR.
Let's see...
MUST means we're dictating to all implementations that they have to support Markdown behavior, in whatever manner it is that they are actually doing something with interpreted docblocks.
RECOMMENDED means that we're saying "docblock writers are trying to highlight some things via Markdown, so you should try your best to honor that... if you can't, well then, it's just text, so no catastrophe".
Either case has the potential to devolve into Github Markdown vs Daring Fireball Markdown vs Wile E. Coyote's ACME Markdown... but that on top of MUST could become a turf war on picking one.
If we keep it in, RECOMMENDED is my vote.
Found some earlier discussions on this topic on #72, so everyone have a look there for additional thoughts for the conversation here.
@dharkness , if you wish to pursue this further, please bring this up as a new thread on the FIG mailing list for discussion -- https://groups.google.com/forum/#!forum/php-fig