Generate API documentation
rossiam opened this issue · 2 comments
Is your feature request related to a problem? Please describe.
Currently, one needs to read through code to find this documentation.
Describe the solution you'd like
There is API documentation published somewhere and linked to from the README.
Describe alternatives you've considered
none
Additional context
none
My current approach thus far is to document code with JsDoc, parse & generate HTML docs with docma, and publish it as a GitHub Page.
I am aware of potential issues with the JsDoc parsing as some of our comments are currently utilizing TypeScript-based features that are friendly to VS Code but not JsDoc parsers. (e.g., @typedef {import('./section')} Section is incompatible with JsDoc and there is no direct equivalent.
Two apparent options:
- Rewrite the docs purely in JsDoc. This makes it a little harder to link to types in other files but can be done with
@moduleI think. - Use TypeScript definition files purely and generate the docs from that. This may be the best solution moving forward. Especially due to the potential that we will migrate to TS.