Since JSDoc seems cerebrally dead...

# Michaël Rouges (a month ago)

Since JSDoc seems cerebrally dead, why the TC39 doesn't make a real documentation standard, evolving with the langage?

Actually, a part of the JS community are exiling to TS to type anything and the rest are just despited by the very outdated version of JSDoc but don't want to add TS to their stack.

IMHO, it's really urgent to have something formal to solve that missing point of my favorite language.

What would it take to make this dream come true, please?

Michaël Rouges - Lcfvs - @Lcfvs

# Bergi (a month ago)

They don't want to add TS to their stack.

Then what else would they want to add to their stack? Notice one doesn't necessarily need the TypeScript Compiler to add TypeScript- or Flow-like type annotations and remove them in a build step - Babel for example could do that just fine as well. Or are you asking for a jsdoc-like thing that lives in comments, where the code can be run without a compilation step?

kind , Bergi

# Andrea Giammarchi (a month ago)
# Andrea Giammarchi (a month ago)
# Dan Peddle (a month ago)

This feels like rich territory for a blog post, if someone feels qualified? Specifically, just running the typescript tool chain for jsdoc annotations, which are excellent for all the reasons mentioned above (comments only, vanilla js etc).

# Jacob Bloom (a month ago)

This feels like rich territory for a blog post, if someone feels

qualified? Specifically, just running the typescript tool chain for jsdoc annotations, which are excellent for all the reasons mentioned above (comments only, vanilla js etc).

Does this count? devblogs.microsoft.com/typescript/how-to-upgrade-to-typescript-without-anybody-noticing-part-1

# Dan Peddle (a month ago)

It’s close, but not quite the same, from a cursory read. Thanks for sharing though.

To respond to the original post, I don’t think something rigidly formal would work out given how many wildly different opinions are out there - thinking out loud, but perhaps something underlying similar to clojures meta information would enable other approaches. The data contained in jsdoc comments is similar... from a certain perspective. Annotations as first class data would let users come up with solutions without parsing comment bodies, and let that data break out of the walled gardens.

I don’t know what the syntax would look like, and still be backward compatible, which is where comments are a clear winner.

# Isiah Meadows (a month ago)

JSDoc is not dead (far from it), people just don't frequently use automated docs generation tooling in the JS community. Most the actual use JSDoc provides nowadays is editor autocomplete hints and integrating with TypeScript (in cases where changing the extension isn't possible for whatever reason), so while it's still useful, it's just not used in the same places it was used previously.


Isiah Meadows contact at isiahmeadows.com, www.isiahmeadows.com

# Michaël Rouges (a month ago)

Sorry, I should be a few more explicit about the needs, I'll try to fix it. (Sorry If my english isn't perfect, it isn't my native language)

Ihmo, the developers needs a strong/robust/uniform way to describe their code, using static types comments and how they are using the language features, enven why they are used for (IDE's autocomplete, doc generation, AST, subsets compilation, bundling, ...).

Actually, there is a lot of things that requires some tricks from several external sources (TS, JSDoc, Clojure, Flow, ...) to nevertheless cover 100% on our code, like @async, the | VS &, the {this} without classes, the spreading, the Symbol references, a lot of things resolved by the @template which doesn't exist in JSDoc, ... where some of the missing features are standardized since 2011, it sounds just crazy!

The real question is: why, when a new language feature is released, the developers need to wait to describe their uses, depending on an ever growing collection of external wills to learn?

If I'm asking that to the TC39, it's because:

  • they strongly discuss a lot of point of views about every language features, then they are the most initiated people to define how to describe them
  • that committee must exist as long as the JS exists, then no risk to have an abandoned spec
  • that committee controls the releases flow, it can control the features comment descriptions to be released at the same time
  • ...

Who is better placed to offer the same guarantees?

The community, like actually? I don't think so, it's why we don't have an unique uptodate solution to rely on it.

But I'm not detracting the community efforts however, it tries to fill the pending gap until today and can be empowered by a real standardization to improve/create a lot of amazing tools (IDE's autocomplete, doc generation, AST, subsets compilation, bundling, ...) on a spec which covers 100% of the language features usages.

Michaël Rouges - Lcfvs - @Lcfvs