Document public functions, add typespec, make private functions private

This is incomplete, but it's a start. Most of the public API is at least roughly documented. I'll have a go at fleshing out the README as well, but I wanted to hold off to see what you think of #5, as that will have an impact on the instructions given.
Should be `@spec`.