3 ms·

JSDoc does not understand typescript syntax though? The typescript language server just kinda plows through/over JSDoc sure, but try getting JSDoc to parse some

• culi 10mo ago
  tuples, `&` operator, and even generics all work perfectly well inside a `@type` declaration. For example: ```js /** * @type {{ * slug: `${string}_${number}`; * id: number; * } & { status?: [code: number, text: string]; }} */ const example = { slug: 'abc_34', id: 34 }; is the exact equivalent of ```ts const example: { slug: `${string}_${number}`; id: number; } & { status?: [code: number, text: string] } = { slug: 'abc_34', id: 34 }; For TS-specific keywords like `satisfies`, there's a corresponding JSDoc keyword like @satisfies. Generics use @template. Is there any specific feature you think is not supported? I'm sure I could work up a TS Playground example.
  • c-hendricks 10mo ago
    > Is there any specific feature you think is not supported 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. Edit: Also, your first edit says Webpack switched from TypeScript to JavaScript, but Webpack source was never written in TypeScript.
    • culi 10mo ago
      We're talking about two different things here. All my examples work perfectly fine with TypeScript https://www.typescriptlang.org/play/?#code/PQKhCgAIUgBAXAngBwKaQN4ajSkDOANgK4DmAXJAAYAkG+8ATgJYB2pAvgPp2vEC2AI1SMOVANw48kZgBNKfISMnRIHSADJMBeAEN4xfAH5KAbQDGAe1moFA4YwA0keKgAe8SgxbsAuuLUOHGBwK1YGSHddfmRCdABebSIySgByXUFzLgBmABZU5zlKPLVJIA 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 https://github.com/jsdoc/jsdoc/issues/2129
      • c-hendricks 10mo ago
        Apologies, my first draft of that comment got deleted on a refresh (mobile) and my posted one left out how I'm probably being too pedantic: the official JSDoc is not TypeScript. 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.
        • culi 10mo ago
          I think you have a valuable point. I kinda purposely avoided explicitly defining what JSDoc is. Instead I'm relying on "the JSDoc we're all familiar with". I said in the post that if your IDE is giving you intellisense from JSDoc comments then you are almost certainly already using TypeScript. That's about as close as I got to defining the JSDoc I'm talking about 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.