From 5a5aac539c621e2c169aa57e825f7bd38365410f Mon Sep 17 00:00:00 2001
From: James Sumners <james.sumners@gmail.com>
Date: Tue, 7 Mar 2017 18:42:57 -0500
Subject: [PATCH 1/3] doc: add active, enroll and unenroll

This commit adds documentation for the public `timers` methods
`active`, `enroll` and `unenroll`.
---
 doc/api/timers.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/doc/api/timers.md b/doc/api/timers.md
index df48905001e19b..1e42d3cc9182ff 100644
--- a/doc/api/timers.md
+++ b/doc/api/timers.md
@@ -162,6 +162,50 @@ added: v0.0.1
 
 Cancels a `Timeout` object created by [`setTimeout()`][].
 
+## Manual Timers
+
+It is possible to make any object a timer. Reusing an existing object as a timer
+slightly reduces memory consumption. Another advantage is that you control
+when the timer will be started.
+
+Example:
+
+```js
+var timers = require('timers');
+var atimer = {
+  _onTimeout: function() {
+    console.log('timeout');
+  }
+}
+
+timers.enroll(atimer, 1000); // make the `atimer` object a timer
+timers.active(atimer); // start the timer
+```
+
+### active(object)
+
+* `object` {Timer} A timer created by [`enroll()`][] to start.
+
+Starts a timer that was created by [`enroll()`][]. If the object has an
+`_onTimeout` method, it will be invoked once the timer has completed.
+
+Once a timer has been started, it can be canceled with [`unenroll()`][].
+
+### enroll(object, delay)
+
+* `object` {object} An object to decorate as a timer.
+* `delay` {number} The number of milliseconds to wait before the timer completes.
+
+Decorate an object as a timer and add it to a list of timers to be processed
+via [the Node.js Event Loop][]. Once decorated, the timer can be started with
+[`active()`][].
+
+### unenroll(object)
+
+* `object` {Timer} A timer that has been started by [`active()`][].
+
+Cancel a timer and reset its state.
+
 
 [the Node.js Event Loop]: https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick
 [`TypeError`]: errors.html#errors_class_typeerror
@@ -171,3 +215,6 @@ Cancels a `Timeout` object created by [`setTimeout()`][].
 [`setImmediate()`]: timers.html#timers_setimmediate_callback_args
 [`setInterval()`]: timers.html#timers_setinterval_callback_delay_args
 [`setTimeout()`]: timers.html#timers_settimeout_callback_delay_args
+[`active()`]: timers.html#timers_active_object
+[`enroll()`]: timers.html#timers_enroll_object_delay
+[`unenroll()`]: timers.html#timers_unenroll_object

From 4d8c0f5a745a6ce499505f267a532e99d9a51c41 Mon Sep 17 00:00:00 2001
From: James Sumners <james.sumners@gmail.com>
Date: Mon, 20 Mar 2017 15:20:24 -0400
Subject: [PATCH 2/3] Incorporate review requests

---
 doc/api/timers.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/doc/api/timers.md b/doc/api/timers.md
index 1e42d3cc9182ff..54762f6f30b474 100644
--- a/doc/api/timers.md
+++ b/doc/api/timers.md
@@ -164,19 +164,26 @@ Cancels a `Timeout` object created by [`setTimeout()`][].
 
 ## Manual Timers
 
-It is possible to make any object a timer. Reusing an existing object as a timer
-slightly reduces memory consumption. Another advantage is that you control
-when the timer will be started.
+It is possible, but not recommended, to make any object a timer. Under special
+circumstances this can be advantageous. However, in general practice, using
+this API is strongly discouraged. This is due to the fact that when using this API
+it is important to track timer enrollment state. A memory leak will occur if a
+timer is enrolled but never unenrolled.
+
+*Note*: This API is considered *unsafe*. Despite being public, it is subject
+to change at any time.
 
 Example:
 
 ```js
-var timers = require('timers');
-var atimer = {
+'use strict';
+
+const timers = require('timers');
+const atimer = {
   _onTimeout: function() {
     console.log('timeout');
   }
-}
+};
 
 timers.enroll(atimer, 1000); // make the `atimer` object a timer
 timers.active(atimer); // start the timer

From b659cb17d359dced977b2a3f56f0149ae611375d Mon Sep 17 00:00:00 2001
From: James Sumners <james.sumners@gmail.com>
Date: Tue, 25 Apr 2017 17:02:09 -0400
Subject: [PATCH 3/3] Incorporate @jasnell latest requested changes

---
 doc/api/timers.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/doc/api/timers.md b/doc/api/timers.md
index 54762f6f30b474..002bdd81d999b7 100644
--- a/doc/api/timers.md
+++ b/doc/api/timers.md
@@ -164,11 +164,9 @@ Cancels a `Timeout` object created by [`setTimeout()`][].
 
 ## Manual Timers
 
-It is possible, but not recommended, to make any object a timer. Under special
-circumstances this can be advantageous. However, in general practice, using
-this API is strongly discouraged. This is due to the fact that when using this API
-it is important to track timer enrollment state. A memory leak will occur if a
-timer is enrolled but never unenrolled.
+It is possible (but not recommended) to make any object a timer. In general
+practice, however, using this API is **strongly discouraged** due to the potential
+for memory leaks should such timers fail to be properly unenrolled.
 
 *Note*: This API is considered *unsafe*. Despite being public, it is subject
 to change at any time.
@@ -182,6 +180,7 @@ const timers = require('timers');
 const atimer = {
   _onTimeout: function() {
     console.log('timeout');
+    timers.unenroll(atimer); // remove the timer from the queue
   }
 };