>> The Javadoc says pretty much the same thing as I wrote above: > > With the crucial exception of how they accomplish what they > accomplish, and in particular, the use of a supplied ExecutorService.
I agree that the Javadoc could provide more detail. But the fact that TaskGroup and TaskSequence might use a different executor service honestly never occurred to me, so I didn't mention it. >> TaskSequence - "Class that runs a sequence of tasks in series and notifies >> listeners when all tasks are complete." >> >> TaskGroup - "Class that runs a group of tasks in parallel and notifies >> listeners when all tasks are complete." > > I think you would agree that those single statements and the others in > the javadocs are not sufficient to understand how the tasks are > executed and therefore when it might be appropriate to use these > classes ... Actually, I think they are sufficient. The only subtlety is which executor service runs the tasks. Otherwise, the classes do exactly what the Javadoc says. I think this may be more of an API design question than a documentation issue. The question is - do you want to allow callers to execute sub-tasks in a different executor service from the parent or not? Or, put another way, is a developer likely to expect that sub-tasks are executed in the same executor as the parent or not? If the former is true, then I think the existing API and documentation is sufficient (though admittedly sparse). If the latter is true, then moving the ExecutorService to the execute() method and adding more detail to the docs would definitely be appropriate.
