JDK-8193276 : Inheritance of unchecked exception @throws specs tar pit
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P4
  • Status: Open
  • Resolution: Unresolved
  • Submitted: 2017-12-08
  • Updated: 2020-08-31
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.
Other
tbd_minorUnresolved
Related Reports
Relates :  
JDK-8187386 - Do not generate javadoc for overridden method with no spec change
Description
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.
Comments
Consider /** * @throws NullPointerException {@inheritDoc} */ @Override public synchronized void forEach(Consumer<? super E> action) { If you actually cared about NPE spec correctness, then in the old world every single implementer of forEach would need to use that boilerplate. But in the new world you would need to as well, since you can't rely on users providing the --overridden-methods=summary flag. This brings the subtlety/water muddiness to a whole new level ...
08-12-2017