RFR: 8252882: Clean up jdk.javadoc and the related parts of jdk.compiler

[Pavel Rappo]

Yet another cleanup change that has accumulated during my work on `DocCommentParser` and other javadoc-related areas of
compiler.

-------------

Commit messages:
 - Misc. cleanup
 - Fixed an embarrassing typo in `{@docroot}`. (Yes, I know that "{@docroot}" is case-insensitive when passed on a command line.)
 - 1. Added missing `bp < buflen` conditions to all but one(!) `while` loops. Those conditions guard against infinite loops. Perhaps in the future we should use `boolean notEOF() { return bp < buflen; }` instead. The only naked `while` loop left is in `erroneous(...)`; that method needs to be revisited anyway. I suspect it's not rolling back correctly.

Changes: https://git.openjdk.java.net/jdk/pull/148/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=148&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8252882
  Stats: 93 lines in 12 files changed: 36 ins; 7 del; 50 mod
  Patch: https://git.openjdk.java.net/jdk/pull/148.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/148/head:pull/148

PR: https://git.openjdk.java.net/jdk/pull/148