Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-6509045

{@inheritDoc} only copies one instance of the specified exception

XMLWordPrintable

    • b31
    • generic, x86
    • generic, linux

        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].

              prappo Pavel Rappo (Inactive)
              tyao Ting-Yun Ingrid Yao (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Created:
                Updated:
                Resolved:
                Imported:
                Indexed: