Consolidating multiple API definitions across the project

[jsantell]

Description of the problem

Right now, typescript definitions, multi-language documentation, and inline JSDoc types in some source files all describe API capabilities and is a struggle to keep in sync.

I'm not terribly familiar with Typescript definitions, but there are a handful of tools to generate documentation from JSDocs etc.. is there a way that there can be one source of truth (typescript defs?) that in turn can generate the documentation? There could possibly be a light test to ensure that changes to signatures are accompanied by the appropriate doc change.

I think this would be very beneficial for the project, reducing conflicting and missing documentation, as well as maintenance cost for the changes. Has there been previous discussions regarding consolidating these docs? Is this something others are interested in, and workable within the project? Any reasons why the API docs content could not be generated by Typescript defs/WebIDL/jsdoc etc?

[looeee]

I like the idea of automatically generating the docs, and I know it's been raised a couple of times before. Especially now that we've added Chinese docs, TS files and JSM files we've significantly increased the burden on anybody contributing code here, and I'd love to find a way to improve that.

The main argument against is that auto-generated docs are often not very user friendly. They end up reading like a machine wrote them and don't do anything beyond tell the user function signatures and properties.

Take pages like ShaderMaterial, WebGLProgram, BufferGeometry, Matrix4. These contain quite a few very useful, hand written, notes on how to use the classes. In these cases, JSDoc style auto-docs would be likely be much less informative and less useful.

We'd need to make sure that there's some way that we can keep this kind of extra info in the generated docs.

Doc pages with live examples are very nice too, it would be a shame if we lost those:

Also, I think multi-language docs are a big problem when it comes to auto-generated docs. I don't know how we'd generate Chinese docs from either JSDoc or TS defs.

Regarding JSDoc in particular, I think that having both TS definitions and JSDoc is redundant. The JSDoc comments that are in the library are just in a couple of the examples I think? I'm in favour of removing those (in fact I already removed all of them from the FBXLoader).

[jsantell]

100% agree @looeee -- losing examples, context and snippets in the docs would be a regression. I think there can be a way to have a machine-readable form of API (testable, inspectable, reduce doc maintanance/inconsistencies) along with a flexible way to any additional content. I think any ideal first iteration of this would result in no visible changes on the docs.

I'm not familiar with the latest I18N tools (nor very familar with current documentation tooling), but with all language docs and typescript defs all needing the same information, there's some way of making this work -- but before that, discussing the requirements and pros & cons are certainly necessary first.

Less about user visible changes, more about making it challenging for docs/typedefs to be out of sync.

W/R/T JSDoc: agreed! Just was another example of redundant info

[donmccurdy]

Can you put JSDoc-style comments into a *.d.ts file? If the only part of JSDoc we care about is the type information then yes, JSDoc is redundant, but it can also be written to contain method descriptions, which *.d.ts files would not have, and much more:

/**
 * Orbit controls allow the camera to orbit around a target.
 *
 * @tutorial orbitcontrols-tutorial
 */
class OrbitControls { ... }

See: https://devdocs.io/jsdoc/about-tutorials

^We'd need a new build script to compile /docs pages, but I think this could produce very similar output to the current pages.

Haven't used this, but related to i18n: https://www.npmjs.com/package/jsdoc-i18n

[jsantell]

Can you put JSDoc-style comments into a *.d.ts file? If the only part of JSDoc we care about is the type information then yes, JSDoc is redundant, but it can also be written to contain method descriptions, which *.d.ts files would not have, and much more:

/**
 * Orbit controls allow the camera to orbit around a target.
 *
 * @tutorial orbitcontrols-tutorial
 */
class OrbitControls { ... }

See: https://devdocs.io/jsdoc/about-tutorials

There are some JSDoc-isms in the current typescript definitions, but not sure how/if they're used with typescript. JSDoc could still be used in source for those annotations that you mention for scenarios that can't be covered by other means (TIL about @tutorial!) -- AFAICT, there's no JSDoc processing of three though, and anecdotally IME JSDoc is more used as a style guide for comments than data to be processed in most projects I've seen that use JSDoc -- my own work included! Possibly due to ES6/class processing issues I've hit (noted in the jsdoc-i18n caveats, edit: possibly due to needing to also satisfy closure compiler rules 😢 ). I wonder if JSDoc tooling could generate the typescript defs, and work in that direction instead.

[mrdoob]

Right now, typescript definitions, multi-language documentation, and inline JSDoc types in some source files all describe API capabilities and is a struggle to keep in sync.

I vote for removing all JSDocs.

[donmccurdy]

I wonder if JSDoc tooling could generate the typescript defs, and work in that direction instead.

That's possible, but since the team doesn't care for inline JSDoc throughout the codebase, the JSDoc would end up in separate files as the TS typings are now. In that situation I think TS typings are easier to write and maintain.

There is tsdoc, which omits type information but includes comments. We could work toward including tsdoc in the typing files, and incrementally beginning to generate API doc pages from those. i18n support will require some experimentation I imagine.

[Mugen87]

#21174 removed TypeScript type declaration files from the core. They are now maintained again at DefinitelyTyped. So I guess this issue can be closed.