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.
Could you rephrase this a bit? I don't like the use of the second person, and the connection to append should be more explicit. Something like "Note that users should assign the input inds slice to the output due to the use of append", except a version that sounds good.