RFR: 8319378: Spec for j.util.Timer::purge and j.util.Timer::cancel could be improved

[Roger Riggs]

On Fri, 3 Nov 2023 20:40:11 GMT, Justin Lu <jlu at openjdk.org> wrote:

> Please review this PR which clarifies the definition of a _cancelled_ task in _j.util.Timer::purge_ and _j.util.Timer::cancel_.
> 
> Timer::purge claims that its return value is the number of tasks in the queue that were cancelled. This can be misleading, as a user can call Timer::cancel, thinking the rest of the tasks in the queue will be canceled (which should be the return value of Timer::purge).
> 
> In actuality, Timer::cancel _discards_ all of the tasks in the queue. For a task to have been _cancelled_, the task itself must have called TimerTask::cancel. 
> 
> This change emphasizes the difference between _discarding_ and _cancelling_ a task.
> Additionally, this change also includes a drive-by update to use an _apiNote_ and _implNote_ tag in the class description.

LGTM

-------------

Marked as reviewed by rriggs (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/16503#pullrequestreview-1716478291