Doc readability

Some subtle changes in the Javadoc with HTML entity escaping, and fixes in whitespace issues in the docs.