add documentation for public interface

This should include parameter semantics and expected value ranges, as well as code that shows exemplary usage.
Ideally, a function self-indicates when it is useful to get used, and when it should not get used if it is ambiguous.