Auto-generated API docs seem not to be using TypeScript files
Closed this issue · 6 comments
If you look at the new API page (https://colorjs.io/api/), many variables and parameters just have any as their types. It looks to me like TypeDoc is pointed at the wrong files (i.e. the JS source instead of .d.ts files).
Here's the page for the Color class, for example: https://colorjs.io/api/classes/color.color
Saw this after reviewing the PR. Yikes! Thanks @MysteryBlokHed for the PR!
@MysteryBlokHed So to be clear, what are the JSDoc comments in the src/ files being used for? There's a lot of duplication currently between those comments and the comments in types/.
@MysteryBlokHed So to be clear, what are the JSDoc comments in the
src/files being used for? There's a lot of duplication currently between those comments and the comments intypes/.
At the moment, I don't think they do anything other than maybe provide IntelliSense while working on the library itself.
I'd be for removing JSDoc from the JavaScript files personally, to avoid confusion for contributors as to where docs come from. Anything that’s currently documented there is probably from before the TypeScript types were added.
Oof, but having the comments in a completely different place instead of when working on the actual source is also very suboptimal. Is there any way to merge the two for typedoc, so we don't have to duplicate them and they can still live together with their definitions?
If not, it may be time to move to TypeScript. :/
Something might be possible with the @inheritdoc JSDoc directive? Maybe it can be used to point to docs from files in some way. But other than that, I don't think there would be any way to use docs from the JS and types from the TS.
Even on DefinitelyTyped (Microsoft's repository for library typings), documentation is just manually copied from the source libraries.