RFR: 8349206: j.u.l.Handler classes create deadlock risk via synchronized publish() method [v5]

[Daniel Fuchs]

On Mon, 24 Feb 2025 19:24:42 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Yep, I think overriding methods are considered usages of API. Implementation applies to the exact method implementation.
>
> There are elements of both implNote and ApiNote, maybe there is clarity in separating the descriptions into two notes. ImplNote says what it does and ApiNote says how to subclass. If both cases, the language of the prose is written to describe in one case and to recommend in the other. My observation was on the mixing of the two. I'm aware the version as written covering difficult to describe behaviors.

I am not sure whether splitting would bring clarity or would make it harder to read. `@apiNote` and `@implNote` are separate sections in the API documentation, so at the minimum a split may require adding some links in both directions. I have the feeling that having the text in a single section might be preferable.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23491#discussion_r1968346862