various tweaks and cleanups

decided to do a PR against your PR so you can see what i am doing.
reformatting only, to not have horizontal scrolling in the doc.