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

XMLWordPrintable

    • Type: Bug
    • Resolution: Unresolved
    • Priority: P3
    • tbd
    • Affects Version/s: 20
    • Component/s: 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.

            Assignee:
            Hannes Wallnoefer
            Reporter:
            Pavel Rappo
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated: