Documentation: Consider generating website docs from JSDoc in .d.ts files

Given prior decisions…

• Maintain .d.ts typings, do not convert to TypeScript. (https://github.com/mrdoob/three.js/issues/15545)
• Keep JSDoc and default values in d.ts files, not source code. (https://github.com/mrdoob/three.js/issues/19919)
• Support i18N in documentation.

… I think there might be an easier option to maintain documentation, typings, and support i18n. The basic workflow would be:

1. Put full documentation (not just default values) in the JSDoc in .d.ts files.
2. Allow translators to use jsdoc-i18n to maintain text translations in a simple sqlite file.
3. Generate documentation — and all translations — from the sqlite file.

One advantage of this is that the documentation and typings are in the same place. I suspect it will also make things much easier for translators, but — to be clear — I don’t know how robust json-i18n’s workflow is. You can find some discussion of this on https://github.com/jsdoc/jsdoc/issues/1127 and https://github.com/documentationjs/documentation/issues/899.

The other effect of this, which could be a downside depending on our preferences, is that it does require a build step for generating the documentation. It’s entirely possible to include headers and example code in JSDoc (example) but this may still limit the customization possible on individual docs pages.

[donmccurdy]

I see, thanks. If JSDoc (or Documentation.js, or similar projects) ever make a really well-supported documentation+i18n workflow we may want to consider it — i don’t think mixing docs and typings would be inherently bad. But it’s not clear that the tools work well enough today to justify switching, especially if we have misgivings about it. I’ll close this suggestion!

[mrdoob]

And I worry that the cost of keeping docs up to date is going to increase as we support more languages, too.

I’ve been thinking about this. In the past we have updated the Chinese docs ourselves.

Now that we have Arabic and Korean, it’s clear to me that we should stop doing that and let the maintainers of the localized docs keep these up to date themselves.

Does #19919 mean that the JSDoc in d.ts files should have default values but no English descriptions of methods?

Yes. That was my understanding.