various changes (mostly docs & formatting)

made some formatting changes while going through the code and I started working on the docs