Perform preliminary research and develop a solution for automatic API reference generation or typings

[shadowusr]

Contribution

• I'd be willing to implement this feature (contributing guide)

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:

• 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
• implement a proof of concept (optional)

Describe the drawbacks of your solution

No response

Describe alternatives you've considered

No response