Adding significant documentation to source files

Trying to be very complete about documentation and code comments here.

There are a few oddities that stood out as I went through the code, which I've marked here with TODO. @egramsta , if you have a chance would you be so kind as to check over the TODO items? (just search TODO in the diff).

This shouldn't change any functionality or output, just update a lot of comments (and in the python, update the style a bit).