Improve documentation coverage

[nblumhardt]

The API surface is currently only partially documented. We should aim to get a basic level of documentation onto every public member, so that we can require documentation during build and therefore encourage improvement in coverage going forward.