JDK-8295800 : When searching documentation for an exception, don't jump over methods that don't mention that exception
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 20
  • Priority: P3
  • Status: In Progress
  • Resolution: Unresolved
  • Submitted: 2022-10-21
  • Updated: 2023-12-05
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
tbdUnresolved
Related Reports
Relates :  
Relates :  
Description
When inheriting documentation for an exception, the search currently transcends though ancestor methods that don't declare that exception either in the throws clause or a @throws tag. 

# Unchecked Exception Case

public interface A {
    /**
     * @throws RuntimeException description
     */
    void m();
}

public interface B extends A {

    @Override void m();
}

public interface C extends B {
    /**
     * @throws RuntimeException {@inheritDoc}
     */
    @Override void m();
}

# Checked Exception Case

public interface A {

    /**
     * @throws Exception           description
     * @throws java.io.IOException description
     */
    void m() throws Exception;
}

public interface B extends A {

    @Override
    void m() throws Exception;
}

public interface C extends B {

    /**
     * @throws java.io.IOException {@inheritDoc}
     */
    @Override
    void m() throws java.io.IOException;
}

If an exception is not mentioned either in the throws clause or a @throws tag, then as far as the exception documentation is concerned, that exception is irrelevant. Since exception documentation is not automatically inherited, the method in B effectively undocuments it. So when C looks for the exception documentation, it should find that B does not have it and cease the search, not continue the search in A.

Although classes and packages sometimes use informal blanket statements such as "Unless otherwise specified, passing a {@code null} argument to any method in this class will cause a {@link NullPointerException} to be thrown", such statements are out of scope of documentation inheritance.


Comments
It wasn't fixed as part of JDK-8285488 (https://github.com/openjdk/jdk/pull/10746) as it makes more sense to fix it together with "directed inheritance" (JDK-8285368).
28-11-2022

This will be fixed as part of https://github.com/openjdk/jdk/pull/10746, in JDK 20.
25-10-2022