I tried to generate the API section of the docs automatically from tsdoc comments. That failed for the follwing reasons:
1. It has been difficult to configure the layout of the API docs, such as, what information to show, how to sort the information, etc. I kept getting less relevant parts of the API show up before the more important parts. I would have had to write a plugin/theme for typedoc to fix that, which doesn't seem worth the effort.
2. The generated docs don't seem to be nearly as useful as the docs shown in the editor. It's just easier to browse the API in an IDE than on a static website.
3. Docs must have a narrative (we're trying to walk the user through the library) which goes against the unordered nature of automatically generated docs.
