RFR [15] 8243563: Doc comments cleanup

[Pavel Rappo]

Dear jfr folk,

Could you consider and review the changeset for https://bugs.openjdk.java.net/browse/JDK-8243563

 http://cr.openjdk.java.net/~prappo/8243563/webrev.00/

This is a cleanup that was triggered by the recent change in the way JavaDoc processes inline tags [1]. In a nutshell, JavaDoc has allowed to begin a line with @ symbol inside inline tags such as {@code} and {@literal}.

While testing that change Jon Gibbons noticed that the resulting documentation was slightly different. One of the differences was caused by unterminated inline tag, a typo in the doc comment for the EventStream#setReuse(boolean) method [2]:

  * If reuse is set to {@code true), an action should not keep a reference

I fixed that and then decided to try out that JavaDoc change by blanketly retrofitting the jdk.jfr doc comments. Regretfully for reviewers, I've done a bit more than I anticipated. Not only do the webrev above fixes that unterminated tag and retrofits the doc comments, it also fixes typos, grammar, and comment skew (including non-compiling examples).

Fixes of typos and grammar are mostly in comments and some are in error messages and *code constructs* such as classes, enum constants, fields, methods, and local variables. I think I was careful and made sure those were in non-exported packages. However, please keep that in mind and pay extra attention while reviewing the change.

The only thing I couldn't fix was the examples from the doc comment for the Recording.setSettings method. I'd appreciate if the experts have a look at and update it.

-Pavel

-------------------
[1] https://bugs.openjdk.java.net/browse/JDK-8241780
[2] http://hg.openjdk.java.net/jdk/jdk/file/cf8b50c400be/src/jdk.jfr/share/classes/jdk/jfr/consumer/EventStream.java#l276