Merge pull request #1526 from johnnyreilly/master

jQuery: more JSDoc goodness

jquery/jquery-tests.ts

@@ -898,6 +898,16 @@ function test_data() {
     $.data(document.getElementById("id"), "", "8").toUpperCase();
 }
 
+function test_removeData() {
+    $("span:eq(0)").text("" + $("div").data("test1"));
+    $("div").data("test1", "VALUE-1");
+    $("div").data("test2", "VALUE-2");
+    $("span:eq(1)").text("" + $("div").data("test1"));
+    $("div").removeData("test1");
+    $("span:eq(2)").text("" + $("div").data("test1"));
+    $("span:eq(3)").text("" + $("div").data("test2"));
+}
+
 function test_dblclick() {
     $('#target').dblclick(function () {
         alert('Handler for .dblclick() called.');
@@ -1814,6 +1824,20 @@ function test_outerWidth() {
         " , outerWidth( true ):" + p.outerWidth(true));
 }
 
+function test_scrollLeft() {
+    var p = $("p:first");
+    $("p:last").text("scrollLeft:" + p.scrollLeft());
+
+    $("div.demo").scrollLeft(300);
+}
+
+function test_scrollTop() {
+    var p = $("p:first");
+    $("p:last").text("scrollTop:" + p.scrollTop());
+
+    $("div.demo").scrollTop(300);
+}
+
 function test_position() {
     var p = $("p:first");
     var position = p.position();
@@ -1832,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

@@ -1067,10 +1067,26 @@ interface JQuery {
      */
     position(): JQueryCoordinates;
 
+    /**
+     * Get the current horizontal position of the scroll bar for the first element in the set of matched elements or set the horizontal position of the scroll bar for every matched element.
+     */
     scrollLeft(): number;
+    /**
+     * Set the current horizontal position of the scroll bar for each of the set of matched elements.
+     *
+     * @param value An integer indicating the new position to set the scroll bar to.
+     */
     scrollLeft(value: number): JQuery;
 
+    /**
+     * Get the current vertical position of the scroll bar for the first element in the set of matched elements or set the vertical position of the scroll bar for every matched element.
+     */
     scrollTop(): number;
+    /**
+     * Set the current vertical position of the scroll bar for each of the set of matched elements.
+     *
+     * @param value An integer indicating the new position to set the scroll bar to.
+     */
     scrollTop(value: number): JQuery;
 
     /**
@@ -1114,19 +1130,64 @@ interface JQuery {
      */
     width(func: (index: number, width: number) => string): JQuery;
 
-    // Data
+    /**
+     * Remove from the queue all items that have not yet been run.
+     *
+     * @param queueName A string containing the name of the queue. Defaults to fx, the standard effects queue.
+     */
     clearQueue(queueName?: string): JQuery;
 
+    /**
+     * Store arbitrary data associated with the matched elements.
+     *
+     * @param key A string naming the piece of data to set.
+     * @param value The new data value; it can be any Javascript type including Array or Object.
+     */
     data(key: string, value: any): JQuery;
+    /**
+     * Store arbitrary data associated with the matched elements.
+     *
+     * @param obj An object of key-value pairs of data to update.
+     */
     data(obj: { [key: string]: any; }): JQuery;
-    data(key?: string): any;
+    /**
+     * Return the value at the named data store for the first element in the jQuery collection, as set by data(name, value) or by an HTML5 data-* attribute.
+     *
+     * @param key Name of the data stored.
+     */
+    data(key: string): any;
+    /**
+     * Return the value at the named data store for the first element in the jQuery collection, as set by data(name, value) or by an HTML5 data-* attribute.
+     */
+    data(): any;
 
+    /**
+     * Execute the next function on the queue for the matched elements.
+     *
+     * @param queueName A string containing the name of the queue. Defaults to fx, the standard effects queue.
+     */
     dequeue(queueName?: string): JQuery;
 
-    removeData(nameOrList?: any): JQuery;
+    /**
+     * Remove a previously-stored piece of data.
+     *
+     * @param name A string naming the piece of data to delete or space-separated string naming the pieces of data to delete.
+     */
+    removeData(name: string): JQuery;
+    /**
+     * Remove a previously-stored piece of data.
+     *
+     * @param list An array of strings naming the pieces of data to delete.
+     */
+    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;