Types (=docs) for IEvent and IPlugin

[kurkle]

Extracted from #7084

If we are going to use typedoc to generate the docs, this is the only way (not going full typescript), that I got the interfaces to get documented.

Re: #7030 (comment)

[kurkle]

IMO the current typedocs are mostly unusable: https://www.chartjs.org/docs/master/typedoc/
Changing the mode to 'file' makes it a lot better.
Still does not bring any plain typedef's to the docs. I could not get typedoc to document the typedefs in code. So thats why I thought that adding the defs in d.ts would be a good idea.

[etimberg]

I'm ok with splitting the type definitions out into their own files

[benmccann]

It looks like there's a couple big problems with --mode file. One is that it doesn't seem to give you enough information to know how to import things and just lists everything together. Another is that the links seem to be broken. E.g. when I click toDegrees it doesn't take me anywhere. I think that we have to use modules since that's the way our code is organized

We might be able to use a different theme if there are any you like more though. E.g. you can do npx typedoc --theme minimal or npm install --save-dev typedoc-neo-theme & npx typedoc --theme ./node_modules/typedoc-neo-theme/bin/default

On a separate but related note, I did find a bug in typedoc today where it seems not to be correctly locating the parent classes: TypeStrong/typedoc#1209

[kurkle]

@benmccann did you actually take a look at the docs under gh-pages? None of the links work (probably due to underscores)

[benmccann]

Ah, I misunderstood what you were saying earlier. Yeah, it's cause of the underscores. Here's some possible solutions: TypeStrong/typedoc#149

[kurkle]

It looks like there's a couple big problems with --mode file. One is that it doesn't seem to give you enough information to know how to import things and just lists everything together. Another is that the links seem to be broken. E.g. when I click toDegrees it doesn't take me anywhere. I think that we have to use modules since that's the way our code is organized

IMO we are to supply one entry point for the library and the source tree structure is kept internal (and not included in npm, because if we publish that, then all those files can not be moved or renamed anymore. or exports removed). Thats why file mode makes sense to me.

We might be able to use a different theme if there are any you like more though. E.g. you can do npx typedoc --theme minimal or npm install --save-dev typedoc-neo-theme & npx typedoc --theme ./node_modules/typedoc-neo-theme/bin/default

I'm not worried about how it looks like at this point, if it provides the needed documentation. Point me to IPLugin documentation in the current version.

[kurkle]

On a separate but related note, I did find a bug in typedoc today where it seems not to be correctly locating the parent classes: TypeStrong/typedoc#1209

Seems to be fixes by file mode:

[benmccann]

Seems to be fixes by file mode

It's fixed on master, so I think it was some other change that fixed it.

It looks like with 'file' mode that all the helpers, etc. get merged into a single namespace and we lose what's Chart.helpers.math vs Chart.helpers.canvas, etc. Is there any reason not to stay with the default mode?

They're working on a new mode 'library', which is supposed to be better than either of the existing modes.

Also, I filed a feature request to support typedefs TypeStrong/typedoc#1214

[kurkle]

Ok, played enough with typedocs in https://github.com/kurkle/color to give up and just write a .d.ts. There is currently no way to get it to generate good docs from JSDoc comments.
If you excludeExtenals, then all internals become externals. None of the modes are actually good. typedoc-plugin-external-module-name is somewhat handy in the default (modules) mode.