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

Inheritance of unchecked exception @throws specs tar pit

XMLWordPrintable

    • Icon: Bug Bug
    • Resolution: Unresolved
    • Icon: P4 P4
    • tbd
    • None
    • tools

      It has long been a source of confusion that @throws specs for unchecked exceptions are not inherited by default. A classic case is Collection#add(E), which lists 5 possible exceptions, but no concrete subclass throws all of these and it's common to throw none of them.

      https://docs.oracle.com/javase/9/docs/api/java/util/Collection.html#add-E-

      If the subclass implementer provides no doc comment, then javadoc will synthesize one that is identical with the interface spec, ***with the unchecked exceptions @throws clauses removed***, which may be what is wanted, but more likely to be correct is an explicit subset like

      /**
       * @throws NullPointerException {@inheritDoc}
       */

      This is so errorprone and relatively unimportant that only recovering Aspergers get this right.

      The addition of --overridden-methods in JDK-8187386 muddies the water further, because when no doc comment is present, then "detail" gives you spec with the @throws discarded while "summary" gives you the "full" inherited spec with the @throws kept. That is, different javadoc options give you different spec!

      See discussion and example on core-libs-dev here:
      http://openjdk.markmail.org/search/?q=overridden+methods+list%3Anet.java.openjdk.core-libs-dev+from%3A%22Stuart+Marks%22#query:overridden%20methods%20list%3Anet.java.openjdk.core-libs-dev%20from%3A%22Stuart%20Marks%22+page:1+mid:nxjl5fqlsstrwthp+state:results

      I have no idea how to get out of this tar pit.

            prappo Pavel Rappo
            martin Martin Buchholz
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

              Created:
              Updated: