JSDoc

Raised as a usability problem by 5 people on Hacker News over 5 years (2021–2025), in 5 threads.

People raised many different problems with JSDoc, but no single problem has yet been raised by 3 people in 3 different months and threads.

Unreviewed issues were grouped by machine: Claude Haiku labelled each comment as a usability complaint, named what it's about and summed up the problem in a line, and a small model grouped similar problems. Nobody has checked them by hand. Expect mistakes.

The newest 5 complaints

Using generic slots in JSDoc is unintuitive in practice, requiring awkward return type workarounds2025-12-14
Verbose and high-friction to annotate parameter, intermediate and anonymous function types2024-07-25
Complicated types are nearly impossible to figure out how to write in JSDoc2022-06-08
Doc comments duplicate code, add extra syntax with no checking, and can drift out of sync2022-01-21
Editor autocomplete fails to recognise many Vue prop completions, so JSDoc becomes pointless2021-01-16