<i18n dev> RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Pavel Rappo]

On Sat, 27 Apr 2024 10:33:42 GMT, Nizar Benalla <duke at 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