From 02348d3eb0d88f81b526e4a20ca358ce49692e0c Mon Sep 17 00:00:00 2001
From: John Reilly <johnny_reilly@hotmail.com>
Date: Thu, 16 Jan 2014 14:00:56 +0000
Subject: [PATCH] jQuery: added proxy / removeData JSDoc + tests

---
 jquery/jquery-tests.ts | 109 +++++++++++++++++++++++++++++++++++++++++
 jquery/jquery.d.ts     |  50 ++++++++++++++++---
 2 files changed, 153 insertions(+), 6 deletions(-)

diff --git a/jquery/jquery-tests.ts b/jquery/jquery-tests.ts
index e024f1dc6..95fed2635 100644
--- a/jquery/jquery-tests.ts
+++ b/jquery/jquery-tests.ts
@@ -946,6 +946,17 @@ function test_removeData() {
     $("span:eq(3)").text("" + $("div").data("test2"));
 }
 
+function test_jQuery_removeData() {
+    var div = $("div")[0];
+    $("span:eq(0)").text("" + $("div").data("test1"));
+    jQuery.data(div, "test1", "VALUE-1");
+    jQuery.data(div, "test2", "VALUE-2");
+    $("span:eq(1)").text("" + jQuery.data(div, "test1"));
+    jQuery.removeData(div, "test1");
+    $("span:eq(2)").text("" + jQuery.data(div, "test1"));
+    $("span:eq(3)").text("" + jQuery.data(div, "test2"));
+}
+
 function test_dblclick() {
     $('#target').dblclick(function () {
         alert('Handler for .dblclick() called.');
@@ -1731,6 +1742,104 @@ function test_hasData() {
     $p.append(jQuery.hasData(p) + " ");
 }
 
+function test_jQuery_proxy() {
+
+    function test1() {
+        var me = {
+            type: "zombie",
+            test: function (event?) {
+                // Without proxy, `this` would refer to the event target
+                // use event.target to reference that element.
+                var element = event.target;
+                $(element).css("background-color", "red");
+
+                // With proxy, `this` refers to the me object encapsulating
+                // this function.
+                $("#log").append("Hello " + this.type + "<br>");
+                $("#test").off("click", this.test);
+            }
+        };
+
+        var you = {
+            type: "person",
+            test: function (event?) {
+                $("#log").append(this.type + " ");
+            }
+        };
+
+        // Execute you.test() in the context of the `you` object
+        // no matter where it is called
+        // i.e. the `this` keyword will refer to `you`
+        var youClick = $.proxy(you.test, you);
+
+        // attach click handlers to #test
+        $("#test")
+        // this === "zombie"; handler unbound after first click
+            .on("click", $.proxy(me.test, me))
+
+        // this === "person"
+            .on("click", youClick)
+
+        // this === "zombie"
+            .on("click", $.proxy(you.test, me))
+
+        // this === "<button> element"
+            .on("click", you.test);
+    }
+
+    function test2() {
+        var obj = {
+            name: "John",
+            test: function () {
+                $("#log").append(this.name);
+                $("#test").off("click", obj.test);
+            }
+        };
+        $("#test").on("click", jQuery.proxy(obj, "test"));
+    }
+
+    function test3() {
+        var me = {
+            // I'm a dog
+            type: "dog",
+
+            // Note that event comes *after* one and two
+            test: function (one?, two?, event?) {
+                $("#log")
+
+                // `one` maps to `you`, the 1st additional
+                // argument in the $.proxy function call
+                    .append("<h3>Hello " + one.type + ":</h3>")
+
+                // The `this` keyword refers to `me`
+                // (the 2nd, context, argument of $.proxy)
+                    .append("I am a " + this.type + ", ")
+
+                // `two` maps to `they`, the 2nd additional
+                // argument in the $.proxy function call
+                    .append("and they are " + two.type + ".<br>")
+
+                // The event type is "click"
+                    .append("Thanks for " + event.type + "ing.")
+
+                // The clicked element is `event.target`,
+                // and its type is "button"
+                    .append("the " + event.target.type + ".");
+            }
+        };
+
+        var you = { type: "cat" };
+        var they = { type: "fish" };
+
+        // Set up handler to execute me.test() in the context
+        // of `me`, with `you` and `they` as additional arguments
+        var proxy = $.proxy(me.test, me, you, they);
+
+        $("#test")
+            .on("click", proxy);
+    }
+}
+
 function test_height() {
     $(window).height();
     $(document).height();
diff --git a/jquery/jquery.d.ts b/jquery/jquery.d.ts
index df6256293..9fc3b1dff 100644
--- a/jquery/jquery.d.ts
+++ b/jquery/jquery.d.ts
@@ -726,17 +726,55 @@ interface JQueryStatic {
      */
     queue(element: Element, queueName: string, callback: Function): JQuery;
 
+    /**
+     * Remove a previously-stored piece of data.
+     *
+     * @param element A DOM element from which to remove data.
+     * @param name A string naming the piece of data to remove.
+     */
     removeData(element: Element, name?: string): JQuery;
 
-    // Deferred
+    /**
+     * A constructor function that returns a chainable utility object with methods to register multiple callbacks into callback queues, invoke callback queues, and relay the success or failure state of any synchronous or asynchronous function.
+     *
+     * @param beforeStart A function that is called just before the constructor returns.
+     */
     Deferred<T>(beforeStart?: (deferred: JQueryDeferred<T>) => any): JQueryDeferred<T>;
 
-    // Effects
-    fx: { tick: () => void; interval: number; stop: () => void; speeds: { slow: number; fast: number; }; off: boolean; step: any; };
+    /**
+     * Effects
+     */
+    fx: {
+        tick: () => void;
+        /**
+         * The rate (in milliseconds) at which animations fire.
+         */
+        interval: number;
+        stop: () => void;
+        speeds: { slow: number; fast: number; };
+        /**
+         * Globally disable all animations.
+         */
+        off: boolean;
+        step: any;
+    };
 
-    // Events
-    proxy(fn: (...args: any[]) => any, context: any, ...args: any[]): any;
-    proxy(context: any, name: string, ...args: any[]): any;
+    /**
+     * Takes a function and returns a new one that will always have a particular context.
+     *
+     * @param fnction The function whose context will be changed.
+     * @param context The object to which the context (this) of the function should be set.
+     * @param additionalArguments Any number of arguments to be passed to the function referenced in the function argument.
+     */
+    proxy(fnction: (...args: any[]) => any, context: Object, ...additionalArguments: any[]): any;
+    /**
+     * Takes a function and returns a new one that will always have a particular context.
+     *
+     * @param context The object to which the context (this) of the function should be set.
+     * @param name The name of the function whose context will be changed (should be a property of the context object).
+     * @param additionalArguments Any number of arguments to be passed to the function named in the name argument.
+     */
+    proxy(context: Object, name: string, ...additionalArguments: any[]): any;
 
     Event: JQueryEventConstructor;