FULL PRODUCT VERSION :
Java(TM) SE Runtime Environment (build 1.6.0-b105)
Java HotSpot(TM) Client VM (build 1.6.0-b105, mixed mode, sharing)
A DESCRIPTION OF THE PROBLEM :
{@inheritDoc}, in the text argument of a method's @throws tag, is documented to "copy the tag text from the corresponding tag up the hierarchy".
The javadoc documentation also states that, "Multiple @throws tags can be used in a given doc comment for the same or different exception".
However, if an interface contains multiple @throws tags for the same exception, an {@inheritDoc} directive only copies from the last of these tags. Multiple {@inheritDoc} directives for the exception result in the text from the last @throws tag being copied repeatedly.
Even if each {@inheritDoc} instance copied the next @throws instance, that would still be wrong, as there is no method to skip an instance - for example, cherry picking the first and third instances while skipping the second.
The only correct behavior is to inherit all @throws instances of the named exception.
STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Write an interface with a single method, declaring multiple @throws tags for the same exception.
Write a class implementing that interface.
Include a @throws tag for the thrown exception, with {@inheritDoc} as the text argument.
EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
All instances of the exception's @throws tags should be copied up the hierarchy.
Throws:
java.lang.IllegalArgumentException - if a is wrong
java.lang.IllegalArgumentException - if b is wrong
java.lang.IllegalArgumentException - if c is wrong
ACTUAL -
Only the final instance is copied up the hierarchy.
Throws:
java.lang.IllegalArgumentException - if c is wrong
REPRODUCIBILITY :
This bug can be reproduced always.
---------- BEGIN SOURCE ----------
public interface Foo {
/**
* @throws IllegalArgumentException if a is wrong
* @throws IllegalArgumentException if b is wrong
* @throws IllegalArgumentException if c is wrong
*/
public abstract void theMethod(int a, int b, int c);
}
public class Bar extends Object implements Foo {
/**
* @throws IllegalArgumentException {@inheritDoc}
*/
public void theMethod(int a, int b, int c) {
}
}
---------- END SOURCE ----------
CUSTOMER SUBMITTED WORKAROUND :
Manually copy the @throws tags, rather than using {@inheritDoc].