From d62143adebf39dc59674a173301cfe750f634c87 Mon Sep 17 00:00:00 2001
From: Mike Deverell <mike@pelotoncycle.com>
Date: Tue, 23 Aug 2016 09:19:55 -0400
Subject: [PATCH] update documentation for new setTimeout behavior

---
 CHANGELOG.md | 16 ++++++++++++++++
 README.md    | 25 +++++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 356e596..b309759 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,22 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [Unreleased]
+### Fixed
+- When [requestAnimationFrame] does not exist, call the callback immediately
+  and ignore further events for 1/60th of a second. Old behavior was to wait
+  1/60th of a second before calling callback.
+
+### Misc
+- Additional documentation in README
+- coveralls.io and travis badges in README
+- additional tests to cover `setTimeout` use case
+
 ## 1.0.0 - 2016-07-30
 ### Added
 - Initial release
+
+
+[requestAnimationFrame]: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
+
+[Unreleased]: https://github.com/pelotoncycle/frame-throttle/compare/v1.0.0...HEAD
diff --git a/README.md b/README.md
index 44e1e6c..1700174 100644
--- a/README.md
+++ b/README.md
@@ -21,9 +21,15 @@ immediately prior to the browser rendering the updated layout to the screen.
 
 To avoid wasting cycles, we can use [requestAnimationFrame] to only run the
 event listener once just before the page is rendered to the screen.
+For browsers that do not support `requestAnimationFrame`, _frame-throttle_
+will fall back to `setTimeout` (see [gotchas](#gotchas) below.)
 
 ## Use
 
+To use _frame-throttle_, simply create your listener, and pass it to the
+`throttle` method. You can then pass the throttled listener to
+`addEventListener` and `removeEventListener` like any other listener:
+
 ```
 var throttle = require('frame-throttle');
 
@@ -34,8 +40,26 @@ var listener = function(e) {
 var throttledListener = throttle(listener);
 
 window.addEventListener('resize', throttledListener);
+window.removeEventListener('resize', throttledListener);
 ```
 
+## Gotchas
+
+There is a slight difference in how `frame-throttle` works that depends on
+whether or not `requestAnimationFrame` exists.
+
+If `requestAnimationFrame` exists, then the callback will be called during the
+animation-frame callback section of the browser's next [browsing context event loop].
+In this case the callback is called at the optimal time because all layout and
+dimensions will be the most up-to-date available before the page is rendered
+to the screen.
+
+If `requestAnimationFrame` does not exist, then the callback will be called
+immediately, and will not be called again for at least 1/60th of a second. This
+allows you to make make adjustments before the next frame renders, but there is
+a small possibility that the information you calculate your changes off of will
+be out of date by the time the next frame renders.
+
 
 [travis-image]: https://travis-ci.org/pelotoncycle/frame-throttle.svg?branch=master
 [travis-url]: https://travis-ci.org/pelotoncycle/frame-throttle
@@ -43,4 +67,5 @@ window.addEventListener('resize', throttledListener);
 [coveralls-image]: https://coveralls.io/repos/github/pelotoncycle/frame-throttle/badge.svg?branch=master
 [coveralls-url]: https://coveralls.io/github/pelotoncycle/frame-throttle?branch=master
 
+[browsing context event loop]: https://html.spec.whatwg.org/multipage/webappapis.html#processing-model-8
 [requestAnimationFrame]: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame