jQuery: promise JSDoc'd

and added test suite

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);

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;