On Mon, 29 Apr 2024 20:02:32 GMT, Pavel Rappo <pra...@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
