clean up doc formatting and comments

just a bunch of formatting, wording and comment cleanups, mostly to the
README file