Props & types documentation

[thure]

This PR introduces API documentation via comments in the code which are compatible with API Extractor. Docs are built post build, and include anything exported by src/index.ts.

[dvdzkwsk]

Great to have some documentation at last! Really appreciate you digging into this.

I do have a question about the workflow: it looks like developers must run build locally before committing, is that correct? That's definitely reasonable given the small number of contributors, but I think a great end game would be to have the documentation generated as part of CI; that way, it would not never get it out sync, such as would happen if a developer only ran start and never build. It would also mean we could avoid checking in generated files, which would help avoid merge conflicts while also making it especially clear that those files are not meant to be edited. I find it helpful to think of the git repo as the source of truth for the library, where any artifacts produced on top of that repo are stored elsewhere.

I've heard that there's a doc site in the works, so perhaps this can wait until then. I definitely want to avoid overcomplicating things from the outset, so please take this less an appeal for immediate change than me wanting to get an idea of where it's heading.

Secondly, and this may again be resolved by the future doc site, I would love to have some of this information consolidated. Right now each type gets its own markdown page, which makes sense from a technical perspective. From a reader's perspective, I'd want to be able to read through the documentation without jumping across multiple tabs.

Not sure what of this is actionable right this moment, but I wanted to get the discussion started.

Other than that, this is miles better than what we had before, so thank you!

[thure]

@davezuko, you have some excellent points.

I think a great end game would be to have the documentation generated as part of CI

Agreed, wholeheartedly. I think we're still exploring what the workflow looks like between the code and a hypothetical docsite, so manually building and committing the docs file was the best way to share these artifacts out, however I hope we can iterate on this process and optimize it to meet the bar you describe.

From a reader's perspective, I'd want to be able to read through the documentation without jumping across multiple tabs.

I agree completely with this as well. I'm not sure if there's an automated way to roll-up the documentation for a component yet, but I'm working with @heath-hamilton to figure out what an ideal target should be, at which point we can look at options. Ultimately I think we're all in agreement that the docs as you see them here are too myopic, and some form of summary would serve the community much better.

[dvdzkwsk]

Sounds good to me, @thure. Approved :).