I've been examining in some detail the (hundreds of) existing Janet docstrings and think I've got a fairly good impression of which features are being used and which not so much [1].

This PR contains some suggested modifications to the description of the subset of Markdown supported by Janet docstrings. It also includes some suggested changes to the terms used to more closely match what I encountered in the most recent CommonMark spec and the Markdown Syntax page. Also, I don't think block quotes are supported so I removed a mention of it. FWIW, in its place, paragraphs are mentioned.

The changed text suggests the mentioning of:

• top-level paragraphs (placing multiple paragraphs in a list item may not work well, which is why this is clarified with the term "top-level")
• single-level ordered and unordered lists (though nested lists do not appear to work and strictly speaking loose lists don't get parsed properly)
• code blocks (fenced [2] and indented)

Though there are some caveats in the above list, in practice I think the docstrings turn out pretty well and I don't personally find the limitations mentioned above to be that important (at least not for the docstrings of Janet itself).

Also, there are some other things that more or less function (e.g. bold, italics, and underlining), but are hardly used and I think it might be worth considering removal of at least underlining (which is not part of Markdown or CommonMark AFAIU) [3]. I didn't mention them in this PR as I thought it would be to discuss first (perhaps elsewhere).

[1] Happy to discuss and provide details to interested parties.

[2] I haven't found an instance of the fenced code block feature being used (though the indented version is used in a few places).

[3] See this issue for more discussion about the underlining feature.