From 925a1282a8db6dc2c202fac8d207e71094dca02b Mon Sep 17 00:00:00 2001
From: johnnyreilly <johnny_reilly@hotmail.com>
Date: Wed, 1 Jan 2014 16:05:06 +0000
Subject: [PATCH] jQuery: JSDoc'd coordinates and added test suite

Added interface to cover coordinates definition.
---
 jquery/jquery-tests.ts | 15 +++++++++++++++
 jquery/jquery.d.ts     | 27 ++++++++++++++++++++++++---
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/jquery/jquery-tests.ts b/jquery/jquery-tests.ts
index 5105dc54aa..e8b11f1827 100644
--- a/jquery/jquery-tests.ts
+++ b/jquery/jquery-tests.ts
@@ -1669,6 +1669,21 @@ function test_width() {
     });
 }
 
+function test_coordinates() {
+    var p = $("p:last");
+    var offset = p.offset();
+    p.html("left: " + offset.left + ", top: " + offset.top);
+
+    $("*", document.body).click(function (event) {
+        var offset = $(this).offset();
+        event.stopPropagation();
+        $("#result").text(this.tagName +
+            " coords ( " + offset.left + ", " + offset.top + " )");
+    });
+
+    $("p:last").offset({ top: 10, left: 30 });
+}
+
 function test_hide() {
     $('.target').hide();
     $('#clickme').click(function () {
diff --git a/jquery/jquery.d.ts b/jquery/jquery.d.ts
index 88dcde5f0a..e0018f6547 100644
--- a/jquery/jquery.d.ts
+++ b/jquery/jquery.d.ts
@@ -348,6 +348,14 @@ interface JQueryEventConstructor {
     new (name: string, eventProperties?: any): JQueryEventObject;
 }
 
+/**
+ * The interface used to specify coordinates.
+ */
+interface JQueryCoordinates {
+    left: number;
+    top: number;
+}
+
 /**
  * The interface used to specify easing functions.
  */
@@ -1023,9 +1031,22 @@ interface JQuery {
      */
     innerWidth(): number;
 
-    offset(): { left: number; top: number; };
-    offset(coordinates: any): JQuery;
-    offset(func: (index: any, coords: any) => any): JQuery;
+    /**
+     * Get the current coordinates of the first element in the set of matched elements, relative to the document.
+     */
+    offset(): JQueryCoordinates;
+    /**
+     * An object containing the properties top and left, which are integers indicating the new top and left coordinates for the elements.
+     *
+     * @param coordinates An object containing the properties top and left, which are integers indicating the new top and left coordinates for the elements.
+     */
+    offset(coordinates: JQueryCoordinates): JQuery;
+    /**
+     * An object containing the properties top and left, which are integers indicating the new top and left coordinates for the elements.
+     *
+     * @param func A function to return the coordinates to set. Receives the index of the element in the collection as the first argument and the current coordinates as the second argument. The function should return an object with the new top and left properties.
+     */
+    offset(func: (index: number, coords: JQueryCoordinates) => JQueryCoordinates): JQuery;
 
     outerHeight(includeMargin?: boolean): number;
     outerHeight(value: number, includeMargin?: boolean): JQuery;