Inherited documentation

An overriding method inherits the parts of its comment that it leaves out, following the JDK 25 search order. {@inheritDoc} copies a part explicitly. Inheritance follows parameter positions, so a renamed parameter keeps its own name as the label.

Transformer documents the contract:

    /** Transforms a value using {@link Widget#convert(int)} when needed.
     * <p>The result preserves {@literal <angle brackets>}.
     * @param input the value to transform
     * @return the transformed value
     * @throws IllegalArgumentException if the value is invalid
     * @throws IllegalArgumentException if the value is empty
     */
    T convert(T input) throws IllegalArgumentException;

Widget overrides it with {@inheritDoc} and renames the parameter:

    /** {@inheritDoc}
     * @param renamed {@inheritDoc}
     * @return {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    @Override public String convert(String renamed) throws IllegalArgumentException { return renamed; }

@Override public String convert(String renamed) throws IllegalArgumentException

Transforms a value using Widget#convert(int) when needed.

The result preserves <angle brackets>.

Parameters:

renamed – the value to transform

Returns:

the transformed value

Throws:

java.lang.IllegalArgumentException – if the value is invalid

if the value is empty

Links in inherited prose still resolve where the original author wrote them. Both @throws descriptions of the same exception are kept.

When documentation can’t be inherited, for example because the ancestor is only on the classpath as a binary, the build warns instead of silently leaving the part out. Add the ancestor’s sources with java_sourcepath; see Build with dependencies and CI.