JSDoc / TSDoc / Comment Spec

[pklaschka]

A space for discussions about

1. What tags can/should get used in the doc comments
2. What spec can be taken to ensure compatibility with editors and still have a productive experience

[ericdrobinson]

For a bit more context, I'll add a bit from this comment this from one of the threads over in PR #51.

TL;DR - We need to be careful about what context we're discussing at all times: TypeScript comments or JavaScript comments. The interpretation of these tags may be handled by the IDE and not the TypeScript language service!

---

As mentioned in this comment, it looks like the TypeScript-recognized list of JSDoc tags is here. That "looks" is emphasized because the explanation seems to suggest that it's context-sensitive (emphasis mine):

currently supported when using JSDoc annotations to provide type information in JavaScript files.

What we haven't clearly stated yet is the context for the JSDoc tags we've been discussing: JavaScript or TypeScript? It appears that in a TypeScript context, JSDoc tags may simply be "comment text". Consider the following code in a TypeScript context:

/** @type {number} */
let test = "hey";

The code snippet above does not produce an error in a TypeScript file, treating the test variable as type any. It does produce an error in a JavaScript file [in VSCode], though!

What this all suggests to me right now is that JSDoc is not a thing that the TypeScript language (read: the language server) actually cares about. Indeed, upon closer inspection, it appears that VSCode interprets the JSDocs in the comments itself when performing certain helpful actions (the standard IntelliSense feautres)!

And this is where TSDoc comes in:

Many... tools in today's web developer community want to interact with TypeScript doc comments. Each of these tools accepts a syntax that is loosely based on JSDoc, but encounters frustrating incompatibilities when attempting to coexist with other parsers.

It seems that TSDoc may eventually present us with a standardized set of tags to use for consistent tooling, but we're not there yet. As such, I think opening a "future discussions" issue to track developments around TSDoc is a great idea.

[Side note: TSDoc has an RFC for a @defaultValue tag 😉]

[ericdrobinson]

Also, I did run across this list of recognized "syntax" for TypeScript itself. It seems as though it might provide some insight as to what JSDoc tags it can interpret in some way... (though no context [JS? TS?] is deducible here...).

[ericdrobinson]

TypeScript 3.8 is adding new support for some JSDoc syntax.

[pklaschka]

TypeScript 3.8 is adding new support for some JSDoc syntax.

That's good to know, although it probably won't affect this issue, since it looks like it's only about "Typescript JS compatibility comments", and not really about "documentation comments", so to speak.

Let's hope that their move in doc comment space will bring improvements in the "documentation doc comment" space with it in the foreseeable future 🙂