From d4aa3b7b4aa2821f849d74aec40d2f84e2e78869 Mon Sep 17 00:00:00 2001
From: tjcrowder <tj@crowdersoftware.com>
Date: Thu, 10 Sep 2009 13:11:30 +0100
Subject: [PATCH] doc: Fleshed out docs on Function#defer.

---
 src/lang/function.js | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/lang/function.js b/src/lang/function.js
index b8b6acb..c8ad45f 100644
--- a/src/lang/function.js
+++ b/src/lang/function.js
@@ -233,6 +233,8 @@ Object.extend(Function.prototype, (function() {
 
   /**
    *  Function#defer(args...) -> Number
+   *  - args (?): Optional arguments to pass into the function.
+   *
    *  Schedules the function to run as soon as the interpreter is idle.
    *
    *  A "deferred" function will not run immediately; rather, it will run as soon
@@ -241,6 +243,18 @@ Object.extend(Function.prototype, (function() {
    *  Behaves much like `window.setTimeout` with a delay set to `0`. Returns an
    *  ID that can be used to clear the timeout with `window.clearTimeout` before
    *  it runs.
+   *
+   *  ### Example
+   *
+   *      function showMsg(msg) {
+   *        alert(msg);
+   *      }
+   *
+   *      showMsg("One");
+   *      showMsg.defer("Two");
+   *      showMsg("Three");
+   *      // Alerts "One", then "Three", then (after a brief pause) "Two"
+   *      // Note that "Three" happens before "Two"
   **/
   function defer() {
     var args = update([0.01], arguments);