-
Bug
-
Resolution: Fixed
-
P4
-
20
-
None
JavaDoc treats checked and unchecked exceptions equally. Documentation for a particular exception is inherited if at least one of the below is true:
* there's a corresponding @throws/@exception tag with explicit {@inheritDoc}
* that exception is listed in the `throws` clause
If neither of the above is true, then no documentation for that particular exception is inherited.
Here are recently discovered issues and suspicious bits in exception documentation for methods in java.util.concurrent that override the ExecutorService.invokeAll set of overloaded methods.
1. java.util.concurrent.AbstractExecutorService#invokeAll*
These two overloaded methods do not inherit documentation for NullPointerException and RejectedExecutionException. Hence, they do not document them. *Should they?* If nothing else, it seems that those methods at least throw NPE.
2. While java.util.concurrent.ForkJoinPool#invokeAll(java.util.Collection<? extends java.util.concurrent.Callable<T>>, long, java.util.concurrent.TimeUnit) has the same issue as the methods above, the second override, public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks), inherits those exceptions from something that does not document them, which is a bug.
Exception documentation inheritance is not transitive. To illustrate that, let A define a method m, which is overridden in A's subtypes B and C, such that B extends A and C extends B. If B.m does NOT throw an exception that A.m throws, then C.m could not inherit that exception's documentation, no matter if C.m documents it in throws or explicitly inheritDocs it.
* there's a corresponding @throws/@exception tag with explicit {@inheritDoc}
* that exception is listed in the `throws` clause
If neither of the above is true, then no documentation for that particular exception is inherited.
Here are recently discovered issues and suspicious bits in exception documentation for methods in java.util.concurrent that override the ExecutorService.invokeAll set of overloaded methods.
1. java.util.concurrent.AbstractExecutorService#invokeAll*
These two overloaded methods do not inherit documentation for NullPointerException and RejectedExecutionException. Hence, they do not document them. *Should they?* If nothing else, it seems that those methods at least throw NPE.
2. While java.util.concurrent.ForkJoinPool#invokeAll(java.util.Collection<? extends java.util.concurrent.Callable<T>>, long, java.util.concurrent.TimeUnit) has the same issue as the methods above, the second override, public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks), inherits those exceptions from something that does not document them, which is a bug.
Exception documentation inheritance is not transitive. To illustrate that, let A define a method m, which is overridden in A's subtypes B and C, such that B extends A and C extends B. If B.m does NOT throw an exception that A.m throws, then C.m could not inherit that exception's documentation, no matter if C.m documents it in throws or explicitly inheritDocs it.