Right now, our public API reference and typings are defined separately. Because of this, we have to manually write both docs and typescript types for our public API. Sometimes they get out of sync.
This needs to be solved by introducing automatic generation of either docs by code or code by docs.
Describe the solution you'd like
We can take one of two routes:
generate typescript typings by docs
generate docs by typescript code
I'd personally take the docs-first approach for the following reasons:
the code doesn't get polluted with multiple-screens-long comments with examples
we have clear public API and before changing anything, you are forced to change docs and think twice about the change
in code-first approach you can give up writing human-readable docs. In docs-first approach, one is more likely to write nice docs
DoD:
carefully weigh pros and cons of these two approaches and pick one
come up with a clear scheme of how everything should work
Contribution
Describe the user story
Right now, our public API reference and typings are defined separately. Because of this, we have to manually write both docs and typescript types for our public API. Sometimes they get out of sync.
This needs to be solved by introducing automatic generation of either docs by code or code by docs.
Describe the solution you'd like
We can take one of two routes:
I'd personally take the docs-first approach for the following reasons:
DoD:
Describe the drawbacks of your solution
No response
Describe alternatives you've considered
No response