Summary
-------
Clarify the specification of `java.util.Timer::purge` and `java.util.Timer::cancel` regarding a *cancelled* task.
Problem
-------
`Timer::purge` claims that its return value is the number of tasks in the queue that were cancelled. This can be misleading, as one may interpret `Timer::cancel` as *cancelling* all the scheduled tasks in the queue, which is not true. 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`.
Solution
--------
Clarify in `Timer::cancel` that the method *discards* and does not *cancel* the tasks. Make it apparent that in order to cancel a task, `TimerTask::cancel` must be invoked.
Additionally, there are some drive-by updates to use the javadoc tags *implNote* and *apiNote* in the `java.Timer`.
Specification
-------------
**In Timer::cancel**
/**
- * Terminates this timer, discarding any currently scheduled tasks.
- * Does not interfere with a currently executing task (if it exists).
+ * Terminates this timer, <i>discarding</i> any currently scheduled tasks.
+ * It should be noted that this method does not <i>cancel</i> the scheduled
+ * tasks. For a task to be considered cancelled, the task itself should
+ * invoke {@link TimerTask#cancel()}.
+ *
+ * <p>This method does not interfere with a currently executing task (if it exists).
* Once a timer has been terminated, its execution thread terminates
* gracefully, and no more tasks may be scheduled on it.
*
...
* <p>This method may be called repeatedly; the second and subsequent
* calls have no effect.
+ * @see TimerTask#cancel()
*/
**In Timer::purge**
/**
- * Removes all cancelled tasks from this timer's task queue. <i>Calling
- * this method has no effect on the behavior of the timer</i>, but
- * eliminates the references to the cancelled tasks from the queue.
+ * Removes all <i>cancelled</i> tasks from this timer's task queue.
+ * <i>Calling this method has no effect on the behavior of the timer</i>,
+ * but eliminates the references to the cancelled tasks from the queue.
* If there are no external references to these tasks, they become
* eligible for garbage collection.
*
* <p>Most programs will have no need to call this method.
* It is designed for use by the rare application that cancels a large
* number of tasks. Calling this method trades time for space: the
- * runtime of the method may be proportional to n + c log n, where n
- * is the number of tasks in the queue and c is the number of cancelled
- * tasks.
+ * runtime of the method may be proportional to {@code n + c log n}, where
+ * {@code n} is the number of tasks in the queue and {@code c} is the number
+ * of cancelled tasks.
*
* <p>Note that it is permissible to call this method from within
* a task scheduled on this timer.
*
* @return the number of tasks removed from the queue.
+ * @see #cancel()
+ * @see TimerTask#cancel()
* @since 1.5
*/
**Add an apiNote tag in class description**
- * <p>Java 5.0 introduced the {@code java.util.concurrent} package and
+ * @apiNote Java 5.0 introduced the {@code java.util.concurrent} package and
* one of the concurrency utilities therein is the {@link
* java.util.concurrent.ScheduledThreadPoolExecutor
* ScheduledThreadPoolExecutor} which is a thread pool for repeatedly
**Add an implNote tag in class description**
- *
- * <p>Implementation note: This class scales to large numbers of concurrently
+ * @implNote This class scales to large numbers of concurrently
* scheduled tasks (thousands should present no problem). Internally,
* it uses a binary heap to represent its task queue, so the cost to schedule
* a task is O(log n), where n is the number of concurrently scheduled tasks.
- *
- * <p>Implementation note: All constructors start a timer thread.
+ * <p> All constructors start a timer thread.
*
* @author Josh Bloch
* @see TimerTask