Add comments and clean up whitespace

[paulusmack]

This adds in most of the useful comments from the internal repository.

It also cleans up the whitespace - it removes trailing carriage-return characters and spaces and trims excess blank lines.

[mikey]

Awesome. Thanks @paulusmack