Merge pull request #1588 from johnnyreilly/master

jQuery: JSDoc Callbacks and tighten up typing

jquery/jquery-tests.ts

@@ -668,6 +668,11 @@ function test_callbacksFunctions() {
     callbacks.add(bar);
     callbacks.fire('world');
     callbacks.disable();
+    
+    // Test the disabled state of the list
+    console.log(callbacks.disabled());
+    // Outputs: true
+
     callbacks.empty();
     callbacks.fire('hello');
     console.log(callbacks.fired());
@@ -2316,6 +2321,27 @@ function test_jQuery() {
     });
 }
 
+function test_fn_extend() {
+    jQuery.fn.extend({
+        check: function () {
+            return this.each(function () {
+                this.checked = true;
+            });
+        },
+        uncheck: function () {
+            return this.each(function () {
+                this.checked = false;
+            });
+        }
+    });
+
+    // Use the newly created .check() method
+    //$( "input[type='checkbox']" ).check();
+    // The above test cannot be run as no way that I know of in TypeScript to model the augmentation of jQueryStatic with dynamically added methods
+    // The below would only work at runtime if extend had first been called.
+    $("input[type='checkbox']")["check"]();
+}
+
 function test_jquery() {
     var a = <any>{ what: "A regular JS object" },
     b = $('body');
@@ -2422,6 +2448,16 @@ function test_jquery() {
     jQuery(function ($) {
         // Your code using failsafe $ alias here...
     });
+
+    $(document.body)
+        .click(function () {
+            $(document.body).append($("<div>"));
+            var n = $("div").length;
+            $("span").text("There are " + n + " divs." +
+                "Click to add more.");
+        })
+    // Trigger the click to start
+        .trigger("click");
 }
 
 function test_keydown() {

jquery/jquery.d.ts

@@ -158,28 +158,98 @@ interface JQueryAjaxSettings {
     xhrFields?: { [key: string]: any; };
 }
 
-/*
-    Interface for the jqXHR object
-*/
+/**
+ * Interface for the jqXHR object
+ */
 interface JQueryXHR extends XMLHttpRequest, JQueryPromise<any> {
+    /**
+     * The .overrideMimeType() method may be used in the beforeSend() callback function, for example, to modify the response content-type header. As of jQuery 1.5.1, the jqXHR object also contains the overrideMimeType() method (it was available in jQuery 1.4.x, as well, but was temporarily removed in jQuery 1.5). 
+     */
     overrideMimeType(mimeType: string): any;
     abort(statusText?: string): void;
 }
 
-/*
-    Interface for the JQuery callback
-*/
+/**
+ * Interface for the JQuery callback
+ */
 interface JQueryCallback {
-    add(...callbacks: any[]): any;
-    disable(): any;
-    empty(): any;
-    fire(...arguments: any[]): any;
+    /**
+     * Add a callback or a collection of callbacks to a callback list.
+     * 
+     * @param callbacks A function, or array of functions, that are to be added to the callback list.
+     */
+    add(callbacks: Function): JQueryCallback;
+    /**
+     * Add a callback or a collection of callbacks to a callback list.
+     * 
+     * @param callbacks A function, or array of functions, that are to be added to the callback list.
+     */
+    add(callbacks: Function[]): JQueryCallback;
+
+    /**
+     * Disable a callback list from doing anything more.
+     */
+    disable(): JQueryCallback;
+
+    /**
+     * Determine if the callbacks list has been disabled.
+     */
+    disabled(): boolean;
+
+    /**
+     * Remove all of the callbacks from a list.
+     */
+    empty(): JQueryCallback;
+
+    /**
+     * Call all of the callbacks with the given arguments
+     * 
+     * @param arguments The argument or list of arguments to pass back to the callback list.
+     */
+    fire(...arguments: any[]): JQueryCallback;
+
+    /**
+     * Determine if the callbacks have already been called at least once.
+     */
     fired(): boolean;
-    fireWith(context: any, ...args: any[]): any;
-    has(callback: any): boolean;
-    lock(): any;
+
+    /**
+     * Call all callbacks in a list with the given context and arguments.
+     * 
+     * @param context A reference to the context in which the callbacks in the list should be fired.
+     * @param arguments An argument, or array of arguments, to pass to the callbacks in the list.
+     */
+    fireWith(context?: any, ...args: any[]): JQueryCallback;
+
+    /**
+     * Determine whether a supplied callback is in a list
+     * 
+     * @param callback The callback to search for.
+     */
+    has(callback: Function): boolean;
+
+    /**
+     * Lock a callback list in its current state.
+     */
+    lock(): JQueryCallback;
+
+    /**
+     * Determine if the callbacks list has been locked.
+     */
     locked(): boolean;
-    remove(...callbacks: any[]): any;
+
+    /**
+     * Remove a callback or a collection of callbacks from a callback list.
+     * 
+     * @param callbacks A function, or array of functions, that are to be removed from the callback list.
+     */
+    remove(callbacks: Function): JQueryCallback;
+    /**
+     * Remove a callback or a collection of callbacks from a callback list.
+     * 
+     * @param callbacks A function, or array of functions, that are to be removed from the callback list.
+     */
+    remove(callbacks: Function[]): JQueryCallback;
 }
 
 /*
@@ -778,12 +848,16 @@ interface JQueryStatic {
 
     Event: JQueryEventConstructor;
 
-    // Internals
+    /**
+     * Takes a string and throws an exception containing it.
+     *
+     * @param message The message to send out.
+     */
     error(message: any): JQuery;
 
-    // Miscellaneous
     expr: any;
     fn: any;  //TODO: Decide how we want to type this
+
     isReady: boolean;
 
     // Properties