Merge pull request #1547 from johnnyreilly/master

jQuery: Add jQuery/$ JSDoc

jquery/jquery-tests.ts

@@ -2103,6 +2103,102 @@ function test_jquery() {
         alert(' b is a jQuery object! ');
     }
     alert('You are running jQuery version: ' + $.fn.jquery);
+
+    $("div.foo");
+
+    $("div.foo").click(function () {
+        $("span", this).addClass("bar");
+    });
+
+    $("div.foo").click(function () {
+        $(this).slideUp();
+    });
+
+    $.post("url.xml", function (data) {
+        var $child = $(data).find("child");
+    });
+
+    // Define a plain object
+    var foo = { foo: "bar", hello: "world" };
+
+    // Pass it to the jQuery function
+    var $foo = $(foo);
+
+    // Test accessing property values
+    var test1 = $foo.prop("foo"); // bar
+
+    // Test setting property values
+    $foo.prop("foo", "foobar");
+    var test2 = $foo.prop("foo"); // foobar
+
+    // Test using .data() as summarized above
+    $foo.data("keyName", "someValue");
+    console.log($foo); // will now contain a jQuery{randomNumber} property
+
+    // Test binding an event name and triggering
+    $foo.on("eventName", function () {
+        console.log("eventName was called");
+    });
+
+    $foo.trigger("eventName"); // Logs "eventName was called"
+
+    $foo.triggerHandler("eventName"); // Also logs "eventName was called"
+
+    $("div > p").css("border", "1px solid gray");
+
+    $("input:radio", document.forms[0]);
+
+    $(document.body).css("background", "black");
+
+    var myForm: HTMLFormElement;
+    $(myForm.elements).hide();
+
+    $("<p id='test'>My <em>new</em> text</p>").appendTo("body");
+
+    $("<a href='http://jquery.com'></a>");
+
+    $("<img>");
+    $("<input>");
+
+    var el = $("1<br>2<br>3"); // returns [<br>, "2", <br>]
+    el = $("1<br>2<br>3 >"); // returns [<br>, "2", <br>, "3 &gt;"]
+
+    $("<div></div>", {
+        "class": "my-div",
+        on: {
+            touchstart: function (event) {
+                // Do something
+            }
+        }
+    }).appendTo("body");
+
+    $("<div></div>")
+        .addClass("my-div")
+        .on({
+            touchstart: function (event) {
+                // Do something
+            }
+        })
+        .appendTo("body");
+
+    $("<div><p>Hello</p></div>").appendTo("body")
+
+    $("<div/>", {
+            "class": "test",
+            text: "Click me!",
+            click: function () {
+                $(this).toggleClass("test");
+            }
+        })
+        .appendTo("body");
+
+    $(function () {
+        // Document is ready
+    });
+
+    jQuery(function ($) {
+        // Your code using failsafe $ alias here...
+    });
 }
 
 function test_keydown() {

jquery/jquery.d.ts

@@ -553,15 +553,71 @@ interface JQueryStatic {
      */
     holdReady(hold: boolean): void;
 
-    (selector: string, context?: any): JQuery;
+    /**
+     * Accepts a string containing a CSS selector which is then used to match a set of elements.
+     *
+     * @param selector A string containing a selector expression
+     * @param context A DOM Element, Document, or jQuery to use as context
+     */
+    (selector: string, context?: Element): JQuery;
+    /**
+     * Accepts a string containing a CSS selector which is then used to match a set of elements.
+     *
+     * @param selector A string containing a selector expression
+     * @param context A DOM Element, Document, or jQuery to use as context
+     */
+    (selector: string, context?: JQuery): JQuery;
+    /**
+     * Accepts a string containing a CSS selector which is then used to match a set of elements.
+     *
+     * @param element A DOM element to wrap in a jQuery object.
+     */
     (element: Element): JQuery;
-    (object: {}): JQuery;
+    /**
+     * Accepts a string containing a CSS selector which is then used to match a set of elements.
+     *
+     * @param elementArray An array containing a set of DOM elements to wrap in a jQuery object.
+     */
     (elementArray: Element[]): JQuery;
+    /**
+     * Accepts a string containing a CSS selector which is then used to match a set of elements.
+     *
+     * @param object A plain object to wrap in a jQuery object.
+     */
+    (object: {}): JQuery;
+    /**
+     * Accepts a string containing a CSS selector which is then used to match a set of elements.
+     *
+     * @param object An existing jQuery object to clone.
+     */
     (object: JQuery): JQuery;
-    (func: Function): JQuery;
-    (array: any[]): JQuery;
+    /**
+     * Specify a function to execute when the DOM is fully loaded.
+     */
     (): JQuery;
 
+    /**
+     * Creates DOM elements on the fly from the provided string of raw HTML.
+     *
+     * @param html A string of HTML to create on the fly. Note that this parses HTML, not XML.
+     * @param ownerDocument A document in which the new elements will be created.
+     */
+    (html: string, ownerDocument?: Document): JQuery;
+    /**
+     * Creates DOM elements on the fly from the provided string of raw HTML.
+     *
+     * @param html A string defining a single, standalone, HTML element (e.g. <div/> or <div></div>).
+     * @param attributes An object of attributes, events, and methods to call on the newly-created element.
+     */
+    (html: string, attributes: Object): JQuery;
+
+    /**
+     * Binds a function to be executed when the DOM has finished loading.
+     *
+     * @param callback A function to execute after the DOM is ready.
+     */
+    (callback: Function): JQuery;
+
     /**
      * Relinquish jQuery's control of the $ variable.
      *