RFR [15] 8243563: Doc comments cleanup

[Erik Gahlin]

Hi Pavel,

Awesome work! Thanks for doing this!

I wish I would have tried to apply {@literal } to a larger segment of code, it would have simplified things. 

I noticed you changed from {@code } to {@link}. I assume the rule is that the first mention should use {@link} and the remaining uses {@code}?

I noticed that you changed the code sample in RecordingStream (L347) from event -> System.out-println(event) to System.out::println. While I agree the latter form is usually preferred, I think in this case it helps if you can see the callback object is an event.

Otherwise, looks good!

Thanks
Erik

> On 24 Apr 2020, at 17:40, Pavel Rappo <pavel.rappo at oracle.com> wrote:
> 
> 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
>