Allow usage of the JSDoc @example caption

[schlusslicht]

What this pull request contains

• full lint/test compliance
• implementation (here)

What this pull request impacts

• runtime of the parsing process will increase per tagLine (@anyTag occurences) by one if-condition, evaluating strict string equality (tagName === "example")
  • if an @example is met, a RegEx-replacement will be executed on the whole line (line.replace(/<\/?caption>/g, "")).

What this pull request does
Strip <caption></caption> tags from @example headings (inside the comment convertor factory).
My use-case and motivation as follows.

So, I'm brewing my own small TypeScript library to season my JavaScript client with. And, of course, I want to document the exposed API to give hints inline and on some nice kitchen table like home-brewed-soup.github.io. As I'm trying to conform to standards, I choose the adequate *doc format, which turns out to be TSDoc. Then I look for a nice tool to extract some nice kitchen table-ready HTML from my TSDoc comments and here I am (thank You! ❤️). As time files by, I'm getting ready to actually enrich my documentation with some nitty-gritty @examples (recipes) and immediately hit the VSCode vs. TSDoc wall regarding the @example (block) formatting:

• Highlight @example jsdoc body as source code microsoft/TypeScript-TmLanguage#693
• Semantics of @example unclear (VSCode disagrees) microsoft/tsdoc#147
• support syntax highlighting when @example + code fence are used at the same time mjbvz/vscode-jsdoc-markdown-highlighting#2

To demonstrate what I'm refering to, here's what happenes when applying a title to an @example block in VSCode (v1.59.1#3866c35):

Dissapointing inline-experience. But typedoc does render this correctly, so no issue there. Still, I want the VSCode inline-experience to be tasty. So I looked around, ate some more soup, and found out, that JSDoc (in contrast to TSDoc) forbits the usage of captions in @example headings. Unless! One may use the <caption></caption> tags, to specify the @example caption. Opened VSCode, tried this out, et voila:

Very nice VSCode inline-experience, right there. And then I gave typedoc a go:

Damn, the markdown isn't rendered (:-(). I did not dig through all Your code, but as I can see the <caption></caption> tags being rendered 1:1 into the HTML output, I'd guess strings enclosed in HTML tags are considered to be pre-rendered and therefore aren't piped through the markdown parser? Which seems correnct, in any other case. But nevermind, I did dig through Your code enough to be able to provide this tiny pull request, which just adds an if-clause at the right place to strip <caption></caption> tags from @example tagLines. After applying the patch:

Yummy! :-)

[Gerrit0]

JSDoc's decision here seems completely inappropriate to me. <caption> is a well defined HTML element. Repurposing it is.. awful.

Incidentally, that's why you don't see markdown being parsed here. It isn't parsed because <caption> isn't a span-level element.

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style *emphasis* inside an HTML block.
...
Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.
https://daringfireball.net/projects/markdown/syntax#html

That said, TypeDoc tries to be flexible enough to generate reasonable docs for projects which do a lot of things... so I'm leaning towards that we should handle this. This really should be an update at the VSCode level to properly handle TSDoc... I might take a look at trying to get them to accept a PR to properly handle your first example before merging this.

[Gerrit0]

microsoft/vscode#132821

[schlusslicht]

This is awesome and I couldn't have done it. Thank You very much. 🙏

[Gerrit0]

Having thought about this a bit more, I think we should go ahead and strip <caption> from example tags, even though it's a horrible use, this will improve interoperability with projects which are coming from JSDoc.