This was my main impetus for writing this article. Modern JSDoc uses the TypeScript language service. You can use generics, utility types, typeguards (including the `is` keyword), regex parsing, etc all with just JSDoc.
I used these features extensively (especially generics) in a personal project and managed to do it all in JSDoc.
Types for classes are poor and often you'll find yourself creating a `.d.ts` file or `.ts` file to export non trivial types - however the target file doesn't know how to consume them.
Regardless, I hardly consider that a "missing basic capability"
I don't know what you mean about types for classes being "poor". Types for classes work exactly the same way
The alternative is to do an inline `const foo = /** @type {import('./foo').x} */ ({})` however this gets messy, repetitive and it's difficult to use algebraic types (e.g. `Event & { detail: string }`)
https://github.com/jsdoc/jsdoc/issues/1917
https://github.com/jsdoc/jsdoc/issues/1917#issuecomment-1250...
```js
/**
* @type {{
* slug: `${string}_${number}`;
* id: number;
* } & { status?: [code: number, text: string]; }}
*/
const example = { slug: 'abc_34', id: 34 };
```ts
const example: {
slug: `${string}_${number}`;
id: number;
} & { status?: [code: number, text: string] } = { slug: 'abc_34', id: 34 };
Is there any specific feature you think is not supported? I'm sure I could work up a TS Playground example.
Yeah, uhm, most of what you've been posting? :). That JSDoc example above gives:
ERROR: Unable to parse a tag's type expression for source file /Work/lol-jsdoc-why/index.js in line 1 with tag title "
type" and text "{{ slug: `${string}_${number}`; id: number;} & { status?: [code: number, text: string]; }}": Invalid type expre
ssion "{ slug: `${string}_${number}`; id: number;} & { status?: [code: number, text: string]; }": Expected "!", "$", "'", "(",
"*", ".", "...", "0", "?", "@", "Function", "\"", "\\", "_", "break", "case", "catch", "class", "const", "continue", "debugger",
"default", "delete", "do", "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "implements", "impor
t", "in", "instanceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "return", "static", "supe
r", "switch", "this", "throw", "true", "try", "typeof", "undefined", "var", "void", "while", "with", "yield", "{", Unicode letter
number, Unicode lowercase letter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter, Unicode uppercase let
ter, or [1-9] but "`" found.
https://www.typescriptlang.org/play/?#code/PQKhCgAIUgBAXAngB...
You are attempting to generate documentation from jsdoc comments using an npm package that is also called "jsdoc". Ofc in this case "JSDoc is not TypeScript". That package only supports the subset of JSDoc that is relevant to it. Though I believe you can use TypeDoc instead if you want to generate documentation from JSDoc that contains typescript types.
In the post I made it explicit that I'm talking about intellisense, developer tooling, type checking etc. You can run `tsc` to do typechecking on a project typed with JSDoc like the examples I've given throughout this thread just fine.
I guess the difference here is I'm coming at this from the perspective of "what is TypeScript used for. Can JSDoc comments substitute that". And the answer is almost completely yes.
Also tbh I've never met anyone that uses that package to generate API docs. I don't think it's a very modern package: https://github.com/jsdoc/jsdoc/issues/2129
Your post is actually one of the more accurate ones compared to others that say "you don't need typescript" with the big caveat that you actually need a whole lot of the typescript ecosystem to make JSDoc work.
I just wish there was an official handover, or a more clear delineation between JSDoc and Typescript JSDoc Extensions.
But given that JSDoc doesn't have any sort of formal spec, I think the distinction you're making is more of a historical than a technical one.
JSDoc has been around for more than twenty years and most implementations have never had most of the capabilities you’re describing.
It is actively misleading for you to say that JSDoc has these capabilities when you’re referring specifically and exclusively to TypeScript’s implementation of JSDoc, or you could say TypeScript’s alternative JSDoc syntax. Closure always used language like that in their documentation, and explicitly called out that they had diverged from standard JSDoc, as they should have. TypeScript’s own documentation sometimes refers to it as their superset of JSDoc, again recognizing that “JSDoc” actually does mean something specific and different.
The fact that there may not be a formal technical spec doesn’t mean you’re not wrong and it’s preposterous to suggest that.
There was established tooling and documentation going back 25 years, and it doesn’t somehow not count just because they didn’t give you a formal grammar…
Wishful thinking on my part that an alternative solution for JSDoc based type checking exists :)