5 ms·

Jsdoc Cheatsheet

34 points by susam 4y ago

emj 4y ago
While I love a standard for API documentation, these kinds of documentation is seldom of use for me when I read code, it is usually the same boiler plate you see in this cheat sheet: "X a number". Git commits are ment to be similarly short there it is the what and why, in code I often feel you need the why and how, rather than what for function arguments.
- alexose 4y ago
  I feel the same way. Maybe it's because I came to programming in a roundabout way (i.e., no formal training), but I just see JSDoc-style annotations as wasted characters. Again, maybe just me. But, my brain doesn't parse them unless the code is already extremely well structured. In which case, why include annotations at all? Or in other words, isn't it always better just to improve the readability of the function itself?
  - gl-prod 4y ago
    They aren't really designed for your brain to parse them; they help your IDE understand quickly what's happening.
- 29athrowaway 4y ago
  If I could downvote this a million times, one click at a time until my mouse button stops working, I would. Documentation tags have a machine readable structure. That structure can be parsed and used for documents, editor hints, diagrams, and even type check validations. Instead of having to traverse the entire callgraph of a function to have an idea of what guarantees it provides, you simply read the documentation tag. This is O(1) instead of O(V+E) where V are the functions and E are how you call them.
  - allendoerfer 4y ago
    > That structure can be parsed and used for documents, editor hints, diagrams, and even type check validations. > Instead of having to traverse the entire callgraph of a function to have an idea of what guarantees it provides, you simply read the documentation tag. > This is O(1) instead of O(V+E) where V are the functions and E are how you call them. Unless of course it is wrong, because it is just a convention for a comment and not actually an enforced type.
    - 29athrowaway 4y ago
      The right direction is: more explicit information, more commitment on a stable contract with explicit guarantees, maximize machine readability. The wrong direction is: less information, no stable contracts, forcing people to guess, complete chaos and anarchy, make up your own format with your own tags that nobody supports.
      - allendoerfer 4y ago
        We are on the same page, which is why I would advise to use TypeScript instead of JSDoc.
        29athrowaway 4y ago
        When you can use it, you should. My comparison was between: - JavaScript with no documentation tags - JavaScript with non-machine readable documentation - JavaScript with documentation tags
- kjksf 4y ago
  JSDoc provides type annotations in comments. They are (mostly) not for you. They are for the tooling, including your editor, to detect that your declared foo(bar: string) but you're calling it as foo(5). The value of JSDoc is the same as value of TypeScript: add static types to your code to detect bugs. And yes, it works in practice. I started using JSDoc quite recently. I don't enjoy adding those type annotation comments but undeniably they (and VS Code tooling, jsconfig.json) detect errors that, if not fixed, would end up blowing up at runtime and causing me to spend more time fixing them.
clarkdale 4y ago
It would be interesting if this documentation was written directly into the code itself. For instance the default value is already right there. TypeScript adds the type information. If there was a way to add comments on each parameter name, so that the compiler didn't remove it, that would be neat. I mean inside the function itself.
- augusto-moura 4y ago
  Flow Type had a way of embedding type code in JS block comments [1]. There is an open issue for Typescript, but it looks it didn't went too far [2] [1]: https://flow.org/en/docs/types/comments/ https://flow.org/en/docs/types/comments/ [2]: https://github.com/microsoft/TypeScript/issues/9694 https://github.com/microsoft/TypeScript/issues/9694
- orta 4y ago
  Here's hoping https://tc39.es/proposal-type-annotations/ https://tc39.es/proposal-type-annotations/ solves this
- eyelidlessness 4y ago
  For what it’s worth, there’s also TSDoc[1] which is TypeScript’s sorta-equivalent spiritual successor, and notably uses the same format as JSDoc. Inline type annotation is great—and I vastly prefer it to JSDoc as a type annotation mechanism—but supporting the breadth of documentation capability in an inline code position would probably be unwieldy no matter how you try to accommodate it. 1: https://tsdoc.org/ https://tsdoc.org/
billti 4y ago
If you’re using VS Code as your editor, its JavaScript editing is powered by the TypeScript engine’s support for JS. The JSDoc support there is pretty good, as are the docs for the syntax supported. https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html https://www.typescriptlang.org/docs/handbook/jsdoc-supported...
- jjice 4y ago
  I wasn't able to sell TypeScript for a new project to by boss, but I noticed that JSDocs gave me a lot of power in the editor at least, and everyone loves a good doc comment. I'm basically getting to live the bastardized TS lifestyle, and honestly, I'm very okay with it.
  - 29athrowaway 4y ago
    My reply to people not wanting to use TypeScript is "Show me your unit tests". They are often full of type validations. So they've already paid the cost of a strongly typed language without any of the benefits. And when type validations are missing their issue tracker is full of type mismatch related bugs. The lazy works twice. Just use types, the computer is better at comparing large amounts of strings than humans.
    - 01ce8c91872dd6d 4y ago
      and my reply to you would be showing you virtually any TS codebase I ever saw. strict typing is great, but the rest of TS features are just trying to put Java into Javascript, empowering people to turn 100 LOC worth of functionality into 1000 LOC of cruft
      - 29athrowaway 4y ago
        Have fun doing extra work: - writing unit tests that will likely be not exhaustive - refactoring your unit tests constantly each time you change something - do all that without the assistance of a compiler telling you what broke - having to read code to infer types by hand All all of that for what? so that your code still breaks. Comparing strings by hand is certainly the best use of human time. If we only had machines capable of doing that. > My velocity is so high! Look at all those "type mismatch" Jira tickets I've closed in the last month! I am a 10xer. I've multiplied my work 10x! - Average TypeScript hater testimonial
Alifatisk 4y ago
Totally forgot about devhints!

34 points by susam 4y ago

emj 4y ago

While I love a standard for API documentation, these kinds of documentation is seldom of use for me when I read code, it is usually the same boiler plate you see in this cheat sheet: "X a number". Git commits are ment to be similarly short there it is the what and why, in code I often feel you need the why and how, rather than what for function arguments.

alexose 4y ago
I feel the same way. Maybe it's because I came to programming in a roundabout way (i.e., no formal training), but I just see JSDoc-style annotations as wasted characters. Again, maybe just me. But, my brain doesn't parse them unless the code is already extremely well structured. In which case, why include annotations at all? Or in other words, isn't it always better just to improve the readability of the function itself?
- gl-prod 4y ago
  They aren't really designed for your brain to parse them; they help your IDE understand quickly what's happening.
29athrowaway 4y ago
If I could downvote this a million times, one click at a time until my mouse button stops working, I would. Documentation tags have a machine readable structure. That structure can be parsed and used for documents, editor hints, diagrams, and even type check validations. Instead of having to traverse the entire callgraph of a function to have an idea of what guarantees it provides, you simply read the documentation tag. This is O(1) instead of O(V+E) where V are the functions and E are how you call them.
- allendoerfer 4y ago
  > That structure can be parsed and used for documents, editor hints, diagrams, and even type check validations. > Instead of having to traverse the entire callgraph of a function to have an idea of what guarantees it provides, you simply read the documentation tag. > This is O(1) instead of O(V+E) where V are the functions and E are how you call them. Unless of course it is wrong, because it is just a convention for a comment and not actually an enforced type.
  - 29athrowaway 4y ago
    The right direction is: more explicit information, more commitment on a stable contract with explicit guarantees, maximize machine readability. The wrong direction is: less information, no stable contracts, forcing people to guess, complete chaos and anarchy, make up your own format with your own tags that nobody supports.
    - allendoerfer 4y ago
      We are on the same page, which is why I would advise to use TypeScript instead of JSDoc.
      - 29athrowaway 4y ago
        When you can use it, you should. My comparison was between: - JavaScript with no documentation tags - JavaScript with non-machine readable documentation - JavaScript with documentation tags
kjksf 4y ago
JSDoc provides type annotations in comments. They are (mostly) not for you. They are for the tooling, including your editor, to detect that your declared foo(bar: string) but you're calling it as foo(5). The value of JSDoc is the same as value of TypeScript: add static types to your code to detect bugs. And yes, it works in practice. I started using JSDoc quite recently. I don't enjoy adding those type annotation comments but undeniably they (and VS Code tooling, jsconfig.json) detect errors that, if not fixed, would end up blowing up at runtime and causing me to spend more time fixing them.

clarkdale 4y ago

It would be interesting if this documentation was written directly into the code itself. For instance the default value is already right there. TypeScript adds the type information. If there was a way to add comments on each parameter name, so that the compiler didn't remove it, that would be neat. I mean inside the function itself.

augusto-moura 4y ago
Flow Type had a way of embedding type code in JS block comments [1]. There is an open issue for Typescript, but it looks it didn't went too far [2] [1]: https://flow.org/en/docs/types/comments/ https://flow.org/en/docs/types/comments/ [2]: https://github.com/microsoft/TypeScript/issues/9694 https://github.com/microsoft/TypeScript/issues/9694
orta 4y ago
Here's hoping https://tc39.es/proposal-type-annotations/ https://tc39.es/proposal-type-annotations/ solves this
eyelidlessness 4y ago
For what it’s worth, there’s also TSDoc[1] which is TypeScript’s sorta-equivalent spiritual successor, and notably uses the same format as JSDoc. Inline type annotation is great—and I vastly prefer it to JSDoc as a type annotation mechanism—but supporting the breadth of documentation capability in an inline code position would probably be unwieldy no matter how you try to accommodate it. 1: https://tsdoc.org/ https://tsdoc.org/

billti 4y ago

If you’re using VS Code as your editor, its JavaScript editing is powered by the TypeScript engine’s support for JS. The JSDoc support there is pretty good, as are the docs for the syntax supported. https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html https://www.typescriptlang.org/docs/handbook/jsdoc-supported...

jjice 4y ago
I wasn't able to sell TypeScript for a new project to by boss, but I noticed that JSDocs gave me a lot of power in the editor at least, and everyone loves a good doc comment. I'm basically getting to live the bastardized TS lifestyle, and honestly, I'm very okay with it.
- 29athrowaway 4y ago
  My reply to people not wanting to use TypeScript is "Show me your unit tests". They are often full of type validations. So they've already paid the cost of a strongly typed language without any of the benefits. And when type validations are missing their issue tracker is full of type mismatch related bugs. The lazy works twice. Just use types, the computer is better at comparing large amounts of strings than humans.
  - 01ce8c91872dd6d 4y ago
    and my reply to you would be showing you virtually any TS codebase I ever saw. strict typing is great, but the rest of TS features are just trying to put Java into Javascript, empowering people to turn 100 LOC worth of functionality into 1000 LOC of cruft
    - 29athrowaway 4y ago
      Have fun doing extra work: - writing unit tests that will likely be not exhaustive - refactoring your unit tests constantly each time you change something - do all that without the assistance of a compiler telling you what broke - having to read code to infer types by hand All all of that for what? so that your code still breaks. Comparing strings by hand is certainly the best use of human time. If we only had machines capable of doing that. > My velocity is so high! Look at all those "type mismatch" Jira tickets I've closed in the last month! I am a 10xer. I've multiplied my work 10x! - Average TypeScript hater testimonial

Alifatisk 4y ago

Totally forgot about devhints!