JDK-6509045 : {@inheritDoc} only copies one instance of the specified exception
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 6,7
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic,linux
  • CPU: generic,x86
  • Submitted: 2007-01-03
  • Updated: 2022-10-13
  • Resolved: 2022-07-06
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.
JDK 19 JDK 20
19 b31Fixed 20Fixed
Related Reports
Blocks :  
Relates :  
Relates :  
Description
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].

Comments
Changeset: 8f24d251 Author: Pavel Rappo <prappo@openjdk.org> Date: 2022-07-06 22:01:12 +0000 URL: https://git.openjdk.org/jdk19/commit/8f24d25168c576191075c7344ef0d95a8f08b347
06-07-2022

A pull request was submitted for review. URL: https://git.openjdk.org/jdk19/pull/116 Date: 2022-07-06 17:05:19 +0000
06-07-2022

Relates to JDK-4525364.
03-06-2022

EVALUATION Sowmya asked me to look into this bug. It needs to be fixed in the javadoc source code, so I am reassigning to Bhavesh.
30-03-2011