Add edoc @private and @doc, and more type annotations

This should hopefully clear up what is and isn't public API at
the moment, as per #1, and clarify what the arguments to some
functions and return values will look like.