Generate documentation and typings from JSDoc?

[valadaptive]

Currently, the documentation seems to be manually maintained and updated alongside the code.

It may be beneficial to move the documentation alongside the code in the form of JSDoc comment blocks, using a tool like jsdoc-to-markdown to generate documentation from it. This would make it easier to update the documentation to match the code, and there are even linting tools that will ensure that the documentation is up-to-date. This would also make the documentation easier to access for people reading the code directly.

In addition, it's even possible to generate TypeScript types from JSDoc automatically. This would ensure that typings are up-to-date in addition to the documentation.

[mtth]

Sounds reasonable. A requirement would be for hosting to be straightforward, including the non-API documentation (advanced usage, etc.).

[joscha]

If we were to continue #479, then we could easily use https://typedoc.org/ to produce this. It has the ability to incorporate custom Markdown as well.