Investigate auto-generated TS API docs

markerikson commented 3 years ago

Writing API docs by hand is a pain. We should look into tools that could at least generate the TS parts and make them browsable, and let us add more hand-written material on top of that.

Some examples of possible tools I've seen:

I do note that when I use that jsdocs tool to view RTK 1.6.0-alpha.2, it doesn't show any of the info from the nested entry points.

Ideally, I'd want something I could embed in a Markdown/MDX file, like <TSApiRef typeName="createAction" />.

I know Lenz's remark-typescript-tools lets us do something a little bit like that in terms of importing docblock content, but what I'm really looking for here is a nicely formatted view of the TS types and API definitions themselves so we don't have to write those by hand.

Other links:

https://twitter.com/rauschma/status/1417515875465367554

orta commented 3 years ago

This is also something I'm looking at/for with the TS Compiler API docs and also for porting Danger JS's reference to Docusaurus - I've done rudimentary work (which is just using the AST parser) when talking with @gr2m but to make reliable and comprehensive you need to do a full type-check across the entire project before you can pull out nested symbols and cross-file references.

The current Danger JS reference uses typedoc to generate a JSON representation of all the relevant docs, I wonder if it's feasible to create something which uses typedoc as a rendering engine

phryneas commented 3 years ago

@orta I'm not sure if TypeDoc would even help with our code base, as I think they also do mostly parsing? At least TSDoc does, which I have been using so far. And since we do stuff like augmenting interfaces from multiple files, that probably won't work.

full type-check across the entire project before you can pull out nested symbols and cross-file references.

You wouldn't have some reference on how something like that would be done? I've been trying to just instrumentalize tsserver for that, but that does it's own formatting and cuts things off when they get too long, so it's not ideal. Also, I just get strings from that, not data structures.

orta commented 3 years ago

Yeah, handling something like the augmentation would require a full compiler pass which is what you're doing there (BTW there's a lot of similarities to twoslash in what you're doing there - which creates a vfs per code block, then tsserver calls on all identifiers )

TSDoc is AST level, and not type level, it's not going to have what you're looking for I think. TypeDoc might because it compiles the entire project in order to work with the type-checker. I think to do it you'll need to use the compiler APIs directly rather than abstracting via the tsserver to get some raw objects to work with

markerikson commented 1 year ago

Not actually TS docs related but don't feel like making a new issue.

https://humeris.org/espresso-shot.html looks interesting for writing typetests.

reduxjs / redux-toolkit

Investigate auto-generated TS API docs #1046