-
Bug
-
Resolution: Unresolved
-
P4
-
None
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 inJDK-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.
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
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.
- relates to
-
JDK-8187386 Do not generate javadoc for overridden method with no spec change
- Closed