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