Docstring review

[danwallach]

Not anything specific, but we need to work through every single docstring and make sure they're consistent with the code behavior. In particular:

• In any possible case where an error might be thrown, this needs to be described in detail.
• Any time we're naming another class, method, or field, we should use the @link notation so we get working hyperlinks.
• For the most part, the API we're providing deals with serialization and deserialization, but we might have a separate SERIALIZATION.md file that explains how we're using io-ts, how it works, and how to deal with its error handling.
• When all the docstrings are converted to HTML, I think we get README.md as well, but we need to make sure other Markdown files we might write also get converted.