Semantics of @example unclear (VSCode disagrees)

[rix0rrr]

Hi,

I'm just dipping my toe into TSDoc, so my apologies in advance if this discussion is out of place, or what I'm about to say is common knowledge. Having said that:

There seems to be disagreement about how @example blocks are supposed to be interpreted, specifically when using VSCode.

If I add an @example block to my doc comment, VSCode responds by nicely syntax-highlighting the following code block:

That's amazing, exactly what I want! However, TSDoc tries to parse the code inside the @example block as "regular" docstrings:

Looks like TSDoc wants me to fence the code block with code delimiters, which is not as nice:

(Indentation by 4 spaces, which normally indicates literal code in MarkDown, doesn't work either, TSDoc still tries to parse the code)

[octogonz]

From a documentation perspective, TSDoc's design seems a little better to me:

• It allows you to explain your example using rich text English, and possibly present more than one code snippet

• It allows your example to use other code languages (e.g. JavaScript, JSON, XML, etc) and specify their syntax highlighting

(Indentation by 4 spaces, which normally indicates literal code in MarkDown, doesn't work either, TSDoc still tries to parse the code)

This was an intentional design decision. TSDoc avoids assigning meaning to whitespace, since it's easy to mess up inside a /** */ frame. Also, unlike Markdown, people writing TSDoc often do not have an immediate rendering feedback loop that helps them predict what it's going to look like on the web site. Syntax rules that count spaces can be highly confusing in that situation (and anyway they are redundant since Markdown has other ways to express the same thing).

I'm not sure what VS Code's approach is based on. Prior to TSDoc I couldn't find any formal spec for how TypeScript doc comments should be interpreted.

That said, you can see from this thread that @example was one of the more dubious tags -- people had some trouble deciding how it should work. Suggestions for improvement would be welcome.

[rix0rrr]

Yeah, I see where you're coming from.

It's just this: we're building a class library that we recommend people to write extensions for using VSCode, and we intend to parse the doc comments using TSDoc, and that means we're stuck in an uncomfortable position where the tools we're recommending people to use are going to disagree on what a particular piece of text means. Specifically, the editor is going to apply confusing syntax highlighting to something that's not actually interpreted as code.

(By the way, I just tried mixing descriptive text and fenced code blocks, and VSCode completely loses it when I do that).

I appreciate that while trying to set a new standard there might be a transitionary period during which things are messed up. I just hope that VSCode and TSDoc can align quickly.

Otherwise, to smooth the transition, is there a possibility to have 2 different tags with different interpretations?

[octogonz]

I appreciate that while trying to set a new standard there might be a transitionary period during which things are messed up. I just hope that VSCode and TSDoc can align quickly.

Yeah, we've been planning for a while to set up a conversation with the VS Code owners and improve alignment between the two projects. I've been delaying this because I thought it would be helpful to first write up the spec draft that codifies the TSDoc syntax and philosophy. But the last couple months most of my time in this area has been focused on shipping API Extractor 7, which will give us a complete application of TSDoc for a production tool. That should be done in the next week or so, but it's taken much longer than expected. In short, you're right, and we're working towards what you're describing, just rather slower than ideal but with plenty of great sounding excuses heheh.

Otherwise, to smooth the transition, is there a possibility to have 2 different tags with different interpretations?

Sure. The TSDoc parser configuration allows you to define custom tags. So you could make a tag @richExample or whatever, which VSCode will not treat specially, so it should fallback to correctly highlighting the code fence.

See this sample code for an example of custom tags.