started to fix documentation; fixed a few coding nits in the process
finished first pass at documentation cleanup