Replace API docs with generated API docs (jsdoc? Something else?)

[LeaVerou]

I experimented with JSDoc a while ago, but it was producing incorrect results (e.g. listing things as globals that were not global). I've saved the status of those experiments in the jsdoc branch. We need something though because the current API docs are pretty, but grossly out of date.

[ai]

I recommend creating .d.ts files with TSDocs (they are very similar to JSDoc).

Here is an example: https://github.com/ai/nanoid/blob/main/index.d.ts

Reasons:

1. TypeScript is a very big deal for modern web development.
2. VS Code and most IDEs have TSDoc support.
3. Types in .d.ts files will improve autocompletion in VS Code and IDEs even for JS users.
4. Good API docs need type information anyway. It is better to use types rather than text.

[LeaVerou]

Totally agree wrt types.

My understanding is that modern editors like VS code read typings from JSDoc comments as well though, right? My VS code has definitely offered hints based on the types it read from jsdoc comments.

If TS doesn't read these, can we generate the .d.ts files from jsdoc comments? What I'm trying to avoid is having to maintain stuff in multiple places, that's exactly why the current API docs are so out of date :/

Also the question remains: even if we have .d.ts files, what do we do for API documentation? We still need to generate something, right?

[ai]

My understanding is that modern editors like VS code read typings from JSDoc comments as well though, right?

Yes, but it works only for simple types like number or string. When you will try declare object with color space, JSDoc will not very useful for that (there are methods, but they are less readable and less maintainable compare to simple types).

Also the question remains: even if we have .d.ts files, what do we do for API documentation?

tsdoc CLI can do it.

[ai]

What I'm trying to avoid is having to maintain stuff in multiple places, that's exactly why the current API docs are so out of date :/

Yes, this is trade-off of having .d.ts files.

I have this problem too and I use this solution:

1. I write all my tests in TypeScript
2. Since all features are covered by tests I also check types
3. If I add some feature or extend API I will need to add tests and there I will find out that I forgot to update types
4. When I will update types (I hope) I will remember to update docs since they are in the same file.

[LeaVerou]

Yes, but it works only for simple types like number or string. When you will try declare object with color space, JSDoc will not very useful for that (there are methods, but they are less readable and less maintainable compare to simple types).

These days there are many ways to declare types in jsdoc, I find some of them quite readable. E.g. for objects you can directly supply the keys as {key1: number, key2: string} etc, without @typedef.

From a quick search it looks like indeed typings files can be generated from jsdoc, see https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html

What do you think?

tsdoc CLI can do it.

That looks nice!

[stof]

Generating the typing files from the JSDoc before publishing the package to the npm registry looks like the best option to me when you author it in JS, as it keeps the source of types near the code.

[LeaVerou]

Yup, agreed with @stof. Question to @ai: do the typings files need to be in the same directory as the JS files, or can they be separate?

[ai]

do the typings files need to be in the same directory as the JS files, or can they be separate?

The simplest way is to replace .js to .d.ts. I think there are ways to put them to another dirs, but I think it doesn't be worth it.

[stof]

@LeaVerou They can be separate if you configure the path in the package.json. but that get more complex when users are expected to also import sub-modules

[LeaVerou]

@LeaVerou They can be separate if you configure the path in the package.json. but that get more complex when users are expected to also import sub-modules

How does it get more complex? (assume my experience with TS is minimal at best)

[Westbrook]

Oooh, types are exciting! I've been following the project for longer than it's been "safe" and this may be the piece that gets my project far enough to really test if the tree shakeability of the library is enough to edge out some other color libraries of size as I look to expand the capabilities of custom elements I work with surfacing color interactions, like sliders or areas or wheels, to developers of creativity applications. 🤩

[LeaVerou]

I think when I tried to use jsdoc, the primary problems were:

• It provides no way of documenting multiple signatures, and we have a fair bit of overloading
• It had a bug where it could deal with things like export default function foo() {} or export default class Bar {} or export default whatever(), it instead wanted me to assign things to a variable and then export it in a separate statement which I found annoying and repetitive. Documentation tools should work with existing code, not expect you to change your code to accommodate their quirks.

Not sure if anyone has any thoughts on these.

[ai]

Not sure if anyone has any thoughts on these

TSDoc is always here waiting for you to try.

Multiple signatures and default export:

interface Func {
  (num: number): number
  (str: string): string
}

declare const func: Func

export default func

[LeaVerou]

TSDoc is always here waiting for you to try.

I never said no to tsdoc, all I said about it was "That looks nice!". If we generate .d.ts files from jsdoc, nothing prevents us from then using tsdoc to generate API docs. 😄

JSDoc does fine with default exports. It just wanted me to change things like:

export default function foo() {

}

to

function foo() {

}

export default foo;

which I was not too happy about. But in the large scheme of things, eh 🤷🏽‍♀️