From 0931add1c36308f3a4e2b1ea1d256ba96b54687f Mon Sep 17 00:00:00 2001
From: John Reilly <johnny_reilly@hotmail.com>
Date: Fri, 10 Jan 2014 13:55:55 +0000
Subject: [PATCH] jQuery: promise JSDoc'd

and added test suite
---
 jquery/jquery-tests.ts | 33 +++++++++++++++++++++++++++++++++
 jquery/jquery.d.ts     |  9 +++++++--
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/jquery/jquery-tests.ts b/jquery/jquery-tests.ts
index 440a56707..6508e81a7 100644
--- a/jquery/jquery-tests.ts
+++ b/jquery/jquery-tests.ts
@@ -1856,6 +1856,39 @@ function test_insertBefore() {
     $("p").insertBefore("#foo");
 }
 
+function test_promise() {
+    var div = $("<div>");
+
+    div.promise().done(function (arg1) {
+        // Will fire right away and alert "true"
+        alert(this === div && arg1 === div);
+    });
+
+    $("button").on("click", function () {
+        $("p").append("Started...");
+
+        $("div").each(function (i) {
+            $(this).fadeIn().fadeOut(1000 * (i + 1));
+        });
+
+        $("div").promise().done(function () {
+            $("p").append(" Finished! ");
+        });
+    });
+
+    var effect = function () {
+        return $("div").fadeIn(800).delay(1200).fadeOut();
+    };
+
+    $("button").on("click", function () {
+        $("p").append(" Started... ");
+
+        $.when(effect()).done(function () {
+            $("p").append(" Finished! ");
+        });
+    });
+}
+
 function test_is() {
     $("ul").click(function (event) {
         var $target = $(event.target);
diff --git a/jquery/jquery.d.ts b/jquery/jquery.d.ts
index f21670ba7..992213c39 100644
--- a/jquery/jquery.d.ts
+++ b/jquery/jquery.d.ts
@@ -1181,8 +1181,13 @@ interface JQuery {
      */
     removeData(list: string[]): JQuery;
 
-    // Deferred
-    promise(type?: any, target?: any): JQueryPromise<any>;
+    /**
+     * Return a Promise object to observe when all actions of a certain type bound to the collection, queued or not, have finished.
+     *
+     * @param type The type of queue that needs to be observed. (default: fx)
+     * @param target Object onto which the promise methods have to be attached
+     */
+    promise(type?: string, target?: Object): JQueryPromise<any>;
 
     // Effects
     animate(properties: any, duration?: any, complete?: Function): JQuery;