#7 add function-level documentation

[Andrew Whitworth]

most functions (or at least most outward-facing ones) should be documented