RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Chen Liang]

On Mon, 29 Apr 2024 20:02:32 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>>> > We will effectively enforce javadoc comment for some method overrides with the checker
>>> 
>>> Those overriding methods don't even appear on the javadoc output. If you go to search for `CompletableFuture.resultNow` on https://docs.oracle.com/en/java/javase/22/docs/api/ you will find nothing. Why are we fixing "broken since tags" that don't even exist in the first place?
>>> 
>>> Also have you looked at the output documentation? Without the `@inheritDoc` tags the content will only have a since tag, which is definitely wrong.
>> 
>> For overriding methods we don't look into the supertype because that's what `javadoc` (the tool) is doing, `javadoc` doesn't look into the supertype and has no special handling or support for `@since` tags in inherited methods.
>> If `javadoc` changes how it deals with method overriding in the future we will match it's behavior and look into the supertype for overriding methods.
>> What is important is that we have to match the rules used in `javadoc`.
>> You can't have both, either you add explicit javadoc comments to these methods or use rules that go against the current behavior or `javadoc`
>
>> Also have you looked at the output documentation? Without the `@inheritDoc` tags the content will only have a since tag, which is definitely wrong.
> 
> This is not how I remember it. Unless written around, `{@inheritDoc}` in a main description is redundant. Let me clarify what I mean. Suppose we have a method:
> 
>     /** Foos. */
>     foo()
> 
> and a couple of other methods that override that method:
> 
>     @Override
>     foo()
> 
>     /**
>      */
>     @Override
>     foo()
> 
>     /**
>      * {@inheritDoc}
>      */
>     @Override
>     foo()
> 
> Now, as far as the main description goes, the above three are equivalent, and the main description is inherited. While the third variant is arguably the most readable, its `{@inheritDoc}` is unnecessary. Explicit `{@inheritDoc}` is only necessary if we want to "write around" the inherited part. For example:
> 
>     /**
>      * Foos with extra steps.
>      * 
>      * {@inheritDoc}
>      * 
>      * Also bars if baz is true.
>      */
>     @Override
>     foo()
> 
> In this case, the generated documentation would be as follows:
> 
>     Foos with extra steps.
>     Foos.
>     Also bars if baz is true.
> 
> `@since` is a block tag. Block tags do not belong to the main description. So, if the goal is to only add a block tag, one does not need to implicitly `{@inheritDoc}` the main description. Does it make sense, Chen?

Thanks for the explanation @pavelrappo. Also I recall inheritDoc has weird interactions with block tags like user-defined `@apiNote` in the JDK, would be nice if you can share more about these (also about the behaviors of inheriting `@throws` etc.

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

PR Comment: https://git.openjdk.org/jdk/pull/18954#issuecomment-2083822988