Support for TypeScript about nudged

[axelpale]

@janne-slamcore Moro! Type definitions would definitely be a nice thing to have. Feel free to give it a go, I can appreciate a PR. I would prefer index.d.ts approach in order to keep things simple.

[axelpale]

@janne-slamcore Thanks for asking. Well, I can see the benefit of declaring the types in JSDoc comment blocks near the actual code. However, that likely implies that we need to migrate all the documentation from the current inhouse-ish Yamdog syntax to JSDoc. While valuable, that is asking quite lot of work, more than I can deal right now.

Of course, you could add the JSDoc without touching the current Yamdog docs. However, it is not preferable for me to need to maintain two kinds of documentation schemes side-by-side in the long term. For a transition period, it is okay, but I think the outcome should be either JSDoc-only or Yamdog-only.

Personally, I am not a big fan of JSDoc for its limitations in documenting complex nested structures and for the use of non-nesting /** for the comment blocks. Still, I acknowledge it has a mature ecosystem and a plethora of tools. Also, my opinion on the downsides can be short-sighted and based on too little experience with JSDoc.

In case you have good experiences with JSDoc and are willing to do the work of migrating the docs to JSDoc and update the "build:docs" script, I will gladly show a green light (and buy you a beer if you reside in or visit Tampere).

Alternatively, I am cautiously okay to the suggestion of including JSDoc type declarations (without touching Yamdog-flavoured docs) but in that case I think I can decide only after I see how the outcome looks like. I fear the outcome is a codebase with 90% of documentation syntax and 10% of actual code somewhere between.

Finally, reconsider the option of manually constructed index.d.ts. It is far for perfect and carries its own maintenance problems but it is simple and standalone. Also, think it as a stepping stone to discover if the above-mentioned heavier options are truly needed.

Feel free to share any further thoughts and opinions.

[lsps9150414]

No problem, I will get back to this when I'm done with my project.

[janne-slamcore]

Any progress on this or shall I take a look?

This guide appears to generate some types from the existing js: https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html but there are a lot of any fields that could use filling in.

https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-d-ts.html#testing-your-types has steps on how to publish types on DefinitelyTyped, but I'm not sure if that's preferred over including the types in this repo.

[janne-slamcore]

@axelpale Are you ok with me modifying the js to include jsdoc type declarations so the auto-generation handles most of the work?