Merge pull request DefinitelyTyped#1492 from johnnyreilly/master

jQuery: JSDoc'd width / height / innerWidth / innerHeight / coordinates

Author: johnnyreilly

jquery/jquery-tests.ts

@@ -1642,6 +1642,48 @@ function test_height() {
     });
 }
 
+function test_width() {
+    // Returns width of browser viewport
+    $(window).width();
+
+    // Returns width of HTML document
+    $(document).width();
+
+    function showWidth(ele, w) {
+        $("div").text("The width for the " + ele + " is " + w + "px.");
+    }
+    $("#getp").click(function () {
+        showWidth("paragraph", $("p").width());
+    });
+    $("#getd").click(function () {
+        showWidth("document", $(document).width());
+    });
+    $("#getw").click(function () {
+        showWidth("window", $(window).width());
+    });
+
+    var modWidth = 50;
+    $("div").one("click", function () {
+        $(this).width(modWidth).addClass("mod");
+        modWidth -= 8;
+    });
+}
+
+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 () {
@@ -1751,13 +1793,11 @@ function test_index() {
 function test_innerHeight() {
     var p = $("p:first");
     $("p:last").text("innerHeight:" + p.innerHeight());
-    p.innerHeight(p.innerHeight() * 2).innerHeight();
 }
 
 function test_innerWidth() {
     var p = $("p:first");
     $("p:last").text("innerWidth:" + p.innerWidth());
-    p.innerWidth(p.innerWidth() * 2).innerWidth();
 }
 
 function test_outerHeight() {

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.
  */
@@ -972,20 +980,73 @@ interface JQuery {
      */
     css(properties: Object): JQuery;
 
+    /**
+     * Get the current computed height for the first element in the set of matched elements.
+     */
     height(): number;
+    /**
+     * Set the CSS height of every matched element.
+     *
+     * @param value An integer representing the number of pixels, or an integer with an optional unit of measure appended (as a string).
+     */
     height(value: number): JQuery;
+    /**
+     * Set the CSS height of every matched element.
+     *
+     * @param value An integer representing the number of pixels, or an integer with an optional unit of measure appended (as a string).
+     */
     height(value: string): JQuery;
-    height(func: (index: any, height: any) => any): JQuery;
+    /**
+     * Set the CSS height of every matched element.
+     *
+     * @param func A function returning the height to set. Receives the index position of the element in the set and the old height as arguments. Within the function, this refers to the current element in the set.
+     */
+    height(func: (index: number, height: number) => number): JQuery;
+    /**
+     * Set the CSS height of every matched element.
+     *
+     * @param func A function returning the height to set. Receives the index position of the element in the set and the old height as arguments. Within the function, this refers to the current element in the set.
+     */
+    height(func: (index: number, height: string) => string): JQuery;
+    /**
+     * Set the CSS height of every matched element.
+     *
+     * @param func A function returning the height to set. Receives the index position of the element in the set and the old height as arguments. Within the function, this refers to the current element in the set.
+     */
+    height(func: (index: number, height: string) => number): JQuery;
+    /**
+     * Set the CSS height of every matched element.
+     *
+     * @param func A function returning the height to set. Receives the index position of the element in the set and the old height as arguments. Within the function, this refers to the current element in the set.
+     */
+    height(func: (index: number, height: number) => string): JQuery;
 
+    /**
+     * Get the current computed height for the first element in the set of matched elements, including padding but not border.
+     */
     innerHeight(): number;
-    innerHeight(value: number): JQuery;
 
+    /**
+     * Get the current computed width for the first element in the set of matched elements, including padding but not border.
+     */
     innerWidth(): number;
-    innerWidth(value: number): JQuery;
 
-    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;
@@ -1001,10 +1062,46 @@ interface JQuery {
     scrollTop(): number;
     scrollTop(value: number): JQuery;
 
+    /**
+     * Get the current computed width for the first element in the set of matched elements.
+     */
     width(): number;
+    /**
+     * Set the CSS width of each element in the set of matched elements.
+     *
+     * @param value An integer representing the number of pixels, or an integer along with an optional unit of measure appended (as a string).
+     */
     width(value: number): JQuery;
+    /**
+     * Set the CSS width of each element in the set of matched elements.
+     *
+     * @param value An integer representing the number of pixels, or an integer along with an optional unit of measure appended (as a string).
+     */
     width(value: string): JQuery;
-    width(func: (index: any, height: any) => any): JQuery;
+    /**
+     * Set the CSS width of each element in the set of matched elements.
+     *
+     * @param func A function returning the width to set. Receives the index position of the element in the set and the old width as arguments. Within the function, this refers to the current element in the set.
+     */
+    width(func: (index: number, width: number) => number): JQuery;
+    /**
+     * Set the CSS width of each element in the set of matched elements.
+     *
+     * @param func A function returning the width to set. Receives the index position of the element in the set and the old width as arguments. Within the function, this refers to the current element in the set.
+     */
+    width(func: (index: number, width: string) => string): JQuery;
+    /**
+     * Set the CSS width of each element in the set of matched elements.
+     *
+     * @param func A function returning the width to set. Receives the index position of the element in the set and the old width as arguments. Within the function, this refers to the current element in the set.
+     */
+    width(func: (index: number, width: string) => number): JQuery;
+    /**
+     * Set the CSS width of each element in the set of matched elements.
+     *
+     * @param func A function returning the width to set. Receives the index position of the element in the set and the old width as arguments. Within the function, this refers to the current element in the set.
+     */
+    width(func: (index: number, width: number) => string): JQuery;
 
     // Data
     clearQueue(queueName?: string): JQuery;