WIP patch to comments and documentation. Note that I ignored the release notes,
as I don't know if it is appropriate to change those retrospectively. A few of the
changes make the prose worse and will likely be rejected, but I included the best
change that came to mind as a starting point for conversation; perhaps somebody
will reply with improvements for v2.