Improve docs, and make the variable names consistent

Expanded most of the documentation, and renamed some of the variables
so that variables that are mutated are (almost) always called dst.
I believe the style is to not name the return unless it is unclear. Am I right @kortschak ?