Grammar should be a markdown superset

[jamiebuilds]

trafficstars

We should obey everything in the CommonMark Spec, only extending things where we need to.

CommonMark doesn't have syntax errors, everything is recovered. In terms of parsing, we should do the same, we should only throw things when extracting information.

Additionally, a standard CommonMark parser/renderer should be able to get 90% of the way to the correct output. i.e. Links should still appear as links even if they don't link to the right thing.

The only question is the handling of @tags. A standard markdown parser would handle them as paragraphs. But then the type syntax could cause problems:

/** @param tuple {[number, string]} description */

If we had a tuple syntax like this, it almost looks like a link in markdown.

Alternatives:

/** @param name `type` description */
/** @param `name` `type` description */

In Markdown these would be parsed as code no matter the contents, which generates reasonable output.

[tmcw]

Love this idea - this jives with using Markdown convention for examples and linking.