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.