- 
    Bug 
- 
    Resolution: Fixed
- 
     P3 P3
- 
    6, 7
- 
        b31
- 
        generic, x86
- 
        generic, linux
| Issue | Fix Version | Assignee | Priority | Status | Resolution | Resolved In Build | 
|---|---|---|---|---|---|---|
| JDK-8289968 | 20 | Pavel Rappo | P3 | Resolved | Fixed | b06 | 
| JDK-8291393 | 19.0.2 | Pavel Rappo | P3 | Resolved | Fixed | b01 | 
| JDK-8291231 | 19.0.1 | Pavel Rappo | P3 | Resolved | Fixed | b04 | 
                    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].
            
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].
- backported by
- 
                    JDK-8289968 {@inheritDoc} only copies one instance of the specified exception -           
- Resolved
 
-         
- 
                    JDK-8291231 {@inheritDoc} only copies one instance of the specified exception -           
- Resolved
 
-         
- 
                    JDK-8291393 {@inheritDoc} only copies one instance of the specified exception -           
- Resolved
 
-         
- is blocked by
- 
                    JDK-8289779 Map::replaceAll javadoc has redundant @throws clauses -           
- Resolved
 
-         
- relates to
- 
                    JDK-8295277 Expand {@inheritDoc} in @throws fully -           
- Resolved
 
-         
- 
                    JDK-8067757 Incorrect HTML generation for copied javadoc with multiple @throws tags -           
- Resolved
 
-         
             (1 relates to, 2 links to)
        
     
        