On Mon, 24 Feb 2025 19:24:42 GMT, Roger Riggs <rri...@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
