Add see tag support by Kingwl · Pull Request #39760 · microsoft/TypeScript (original) (raw)

and more generally, if there's any progress from the TS/VSCode team(s) in terms of better support for tsdoc,

TSDoc and the compiler seem to take somewhat different approaches today:

• My impression is the compiler's priority is to correctly parse a subset of very common coding patterns, as determined by a forensic sample of real world code. This means its grammar is heuristic and relatively simplistic. It will necessarily misinterpret many TSDoc syntaxes. For example, you can't reliably parse `@see` or \@see or <tag title="@see" /> without full a Markdown-like engine.
• By contrast, TSDoc's approach is prescriptive: Although the spec is incomplete today, the aim is to arrive at a rigorous spec. In strict mode, the parser actually issues error messages for malformed inputs (whereas CommonMark has no concept of an "incorrect" input, for example). It's also pretty good at handling comments that weren't authored for TSDoc, but that's a secondary aim.

As such TSDoc would be a somewhat heavyweight piece to incorporate into the compiler. (Not in terms of kilobytes, but in terms of complexity and upkeep.) And doing so might drag the compiler into the rabbit hole of enterprise documentation systems, which is a delightful but surprisingly complex space. This would benefit developers who write rich documentation and adopt TSDoc, but they are a minority. So the current situation is understandable, if not ideal.

An easy way out would be for the compiler to expose a plugin API enabling its comment parser to be replaced. This way, developers could opt-in to TSDoc, and there wouldn't need to be any close coordination between the two projects. This idea was brought up in my last chat with the TypeScript folks, and it seemed to align pretty well with their roadmap for extensibility. It seems like a feasible and pretty good solution.