From 0d8bdec36ed81a3bbe0214869cbb73c2bb479fdb Mon Sep 17 00:00:00 2001
From: John Reilly <johnny_reilly@hotmail.com>
Date: Tue, 21 Jan 2014 13:38:58 +0000
Subject: [PATCH] jQuery: JSDoc Callbacks and tighten up typing

---
 jquery/jquery-tests.ts |  5 +++
 jquery/jquery.d.ts     | 98 ++++++++++++++++++++++++++++++++++++------
 2 files changed, 89 insertions(+), 14 deletions(-)

diff --git a/jquery/jquery-tests.ts b/jquery/jquery-tests.ts
index 1b2fb5d16c..6981118e15 100644
--- a/jquery/jquery-tests.ts
+++ b/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());
diff --git a/jquery/jquery.d.ts b/jquery/jquery.d.ts
index 9b412c5b53..d76e918c91 100644
--- a/jquery/jquery.d.ts
+++ b/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;
 }
 
 /*