On Sat, 27 Apr 2024 10:33:42 GMT, Nizar Benalla <d...@openjdk.org> wrote:
> 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?
-------------
PR Comment: https://git.openjdk.org/jdk/pull/18954#issuecomment-2083562083
