RFR: 8330954: Fix remaining `@since` tags in `java.base`
Chen Liang
liach at openjdk.org
Sun May 5 23:33:05 UTC 2024
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
More information about the core-libs-dev
mailing list