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 thought about it for a bit while I was doing it, and depending on your perspective,

dst[i] = dst[i] + ...

Makes no sense unless the dst on the left is not the same dst on the right.  That might have just been a bit of functional programming thinking sneaking in though.

I'm fine with "at the return of the function" - I just thought writing it out would make it easier to understand.