Support for typescript types

[simonseyock]

As it is possible to typecheck jsdoc comments with the typescript compiler it is more and more common to use typescript types in jsdoc comments. It would be really great if those would be supported by jsdoc as well.

I work sometimes on https://github.com/openlayers/openlayers which is a library that uses this approach. For us it would be great if jsdoc would support the import(..) and intersection (A & B) syntax. Other useful things would be:

• arrow functions as types
• tuples Support Tuples #1703 How to document array elements? #1073
• key types in objects [Question] Other object's properties eq to {[key:string]: string} in TypeScript #1692

and probably some more that I don't remember on the fly.

I see that the main work would need to be done on the parser side. I opened an issue in catharsis: hegemonic/catharsis#64, but the author does not seem to have that much time to discuss issues. While having a little experience writing PEG.js grammars I do not see myself creating a complete PEG.js grammar for typescript types in my free time. I did, however, write a pratt parser for jsdoc types that supports jsdoc, closure and typescript modes (this was inspired by an issue by the catharsis author: hegemonic/catharsis#54). The library I created can be found here: https://github.com/simonseyock/jsdoc-type-pratt-parser and it runs all tests of catharsis and many more. It produces differing results for some expressions in closure mode though, but I tried to verify all of these differing results by directly inputting the expression into the closure compiler.

I also included a catharsis compatibility mode that converts the results into catharsis syntax, but in that step the new features are not included and some detail information about the types is lost.

So if there is interest this library can be used. I could slowly start to work on an PR that replaces catharsis if that would be wanted. For this it would be nice to know if all use of catharsis is done in this repository or if there are libraries included here which in turn include catharsis.

The development of my mentioned library is not finalized and I am open for any kind of discussion.

What do you think?

[simonseyock]

I just noticed that @hegemonic the author of catharsis is also the main contributor of jsdoc. Maybe switching to another parsing library might reduce the work that is needed for this project?

[onsummer]

Thanks for contribution!
Hope to support typescript tuples soon.

Just like:

/**
 * @param {[number, number, number]} - 3 components array for genarate Vec3
 */
const vec3FromArray = (arr) => {
  return new Vec3(arr[0], arr[1], arr[2])
}

[gerardolima]

hey, @simonseyock, is there progress on supporting TypeScript? JSDoc is a great documentation language and some editors already support it very well (ie VSCode); maybe could it be some work already done that could be reused in jsdoc? It would be great to generate documentation from code on TypeScript projects too.

[simonseyock]

JsDoc does not seem to be developed actively for some time now, or at least does not seem to plan to support typescript at the moment. As you can see in my post I wrote an own parsing engine, but I never got an answer here. If you want that change you probably need to fork jsdoc.

[simonseyock]

The engine is working and is already used in another project.

[telamon]

I'm a bit curious if overloading JSDoc with TS really is a good idea..
I'm the maintainer of a library and wanted to provide some nice docs for both JS and TS developers.

The only issue is that the nonstandard TS-syntax breaks JSDoc parsing making vs-code the only thing that can benefit from the annotations.

I'm a bit stumped.
I had expected to at least be able to output markdown while 'type'-support a bonus for those who feel the need for it.
What should I do?

[simonseyock]

@telamon a really big benefit of typescript types in jsdoc is that not only the IDE, but also the typescript compiler can understand, typecheck and create declarations for them: https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html

The jsdoc project itself will probably not support typescript if it is not forked, but there exist some other solutions that can also handle typescript. For example there is https://typedoc.org/, but there exist other projects as well. I don't know if this answers you questions, as I did not completely understood what you really want to achieve. A documentation that takes into account typescript types is suitable for both typescript and javascript developers in my opinion, it only contains additional information that can also be useful to the javascript developer.

EDIT: typedoc supports javascript files: https://typedoc.org/options/configuration/#javascript-files

[telamon]

@simonseyock personally i fail to see the benefits you mention.

JSDoc is most likely feature complete, hence not maintained.
I'm a bit dissapointed because I had wrongly assumed that adding @type lines would make both JS-developers and TS-developers happy alike. I was wrong..

What I find concerning is that TS-expressions break JSDoc's primary function, which is to generate documentation from source.

And as such I don't enjoy the thought of invading JSDoc-specs with foreign annotations, especially when there is no new tooling built that performs the primary function.

After a week of JSDoc + Types:

/** @type {(a: import('lib').SomeType, b: { c: number, d: (n: 0|1|Array<string>) => boolean? }) => void}  Function with a weak-ref to a foreign type, takes callback as second parameter, is this visible? */

• Code written inside comments is neither helpful to humans nor machines.
• @typedef is ok, but @type {expression} provides a lazy way to meta-program without producing value.
• import has to go, the static-analyzer is a guest in your code base, not a citizen.

---

edit

As a JS developer i truly wish to support this feature.
But please consider some alternative to {expression} as it breaks tools.

[simonseyock]

@telamon This issue is stale for 2 years now and there is no response from the developers. There are no plans to implement this.

If you have problems with typescript support inside jsdoc comments in general you should talk to the typescript developers.

(edited)

[telamon]

@simonseyock I understand

I don't think I would be able to reach an agreement with a typescript developer. If you know any could you please forward my concerns? Thank you

[simonseyock]

@telamon I am not associated with the typescript project in any way and don't know any of their developers. You could always open an issue there.

[telamon]

I understand, it's just... I've had beer with some real typescript developers and they nod when I tell them that overreliance on static analysis just pushes the real problem forward but then they smile and say "Then we'll just write a static analyzers for that problem"...

I think they're coding rust now.
Point is I can't talk to them, they're impossible.