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

When searching documentation for an exception, don't jump over methods that don't mention that exception

XMLWordPrintable

    • Icon: Bug Bug
    • Resolution: Unresolved
    • Icon: P3 P3
    • tbd
    • 20
    • tools
    • None

      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.

            hannesw Hannes Wallnoefer
            prappo Pavel Rappo (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated: