JSDoc comments completed

typeahead/typeahead.d.ts

@@ -3,7 +3,54 @@
 // Definitions by: Ivaylo Gochkov <https://github.com/igochkov/>
 // Definitions: https://github.com/borisyankov/DefinitelyTyped
 
-/// <reference path="../jquery/jquery.d.ts"/>
+/// <reference path="jquery.d.ts"/>
+
+interface JQuery {
+    /**
+      * Turns an input[type="text"] element into a typeahead.
+      *
+      * @constructor
+      * @param dataset Single dataset
+      */
+    typeahead(dataset: Twitter.Typeahead.Dataset): JQuery;
+
+    /**
+      * Turns an input[type="text"] element into a typeahead.
+      *
+      * @constructor
+      * @param dataset Array of datasets
+      */
+    typeahead(datasets: Twitter.Typeahead.Dataset[]): JQuery;
+
+    /**
+     * Destroys previously initialized typeaheads. This entails reverting 
+     * DOM modifications and removing event handlers.
+     *
+     * @constructor
+     * @param methodName Method 'destroy'
+     */
+    typeahead(methodName: 'destroy'): JQuery;
+
+    /**
+      * Sets the current query of the typeahead. This is always preferable to 
+      * using $("input.typeahead").val(query), which will result in unexpected 
+      * behavior. To clear the query, simply set it to an empty string.
+      *
+      * @constructor
+      * @param methodName Method 'setQuery'
+      * @param query The query to be set
+      */
+    typeahead(methodName: 'setQuery', query: string): JQuery;
+
+    /**
+      * Accommodates the destroy and setQuery overloads.
+      *
+      * @constructor
+      * @param methodName Method name ('destroy' or 'setQuery')
+      * @param query The query to be set in case method 'setQuery' is used.
+      */
+    typeahead(methodName: string, query: string): JQuery;
+}
 
 declare module Twitter.Typeahead {
     /**
@@ -51,79 +98,149 @@ declare module Twitter.Typeahead {
           */
         footer?: any;
         /**
-          * An array of {Twitter.Typeahead.Datum}.
+          * An array of datums or strings.
           */
         local?: any[];
         /**
           * Can be a URL to a JSON file containing an array of datums or, 
-          * if more configurability is needed, a prefetch options object 
-          * {Twitter.Typeahead.PrefetchOptions}.
+          * if more configurability is needed, a prefetch options object.
           */
         prefetch?: any;
         /**
           * Can be a URL to fetch suggestions from when the data provided by 
           * local and prefetch is insufficient or, if more configurability is 
-          * needed, a remote options object {Twitter.Typeahead.RemoteOptions}.
+          * needed, a remote options object.
           */
         remote?: any;
     }
 
+    /**
+      * Prefetched data is fetched and processed on initialization. 
+      * If the browser supports localStorage, the processed data will be cached 
+      * there to prevent additional network requests on subsequent page loads.
+      */
     interface PrefetchOptions {
+        /**
+          * A URL to a JSON file containing an array of datums. Required.
+          */
         url: string;
+
+        /**
+          * The time (in milliseconds) the prefetched data should be cached 
+          * in localStorage. Defaults to 86400000 (1 day).
+          */
         ttl?: number;
+
+        /**
+          * A function that transforms the response body into an array of datums.
+          *   
+          * @param parsedResponse Response body
+          */
         filter?: (parsedResponse: any) => Datum[];
     }
 
+    /**
+      * Remote data is only used when the data provided by local and prefetch
+      * is insufficient. In order to prevent an obscene number of requests 
+      * being made to remote endpoint, typeahead.js rate-limits remote requests.
+      */
     interface RemoteOptions {
+        /**
+          * A URL to make requests to when the data provided by local and 
+          * prefetch is insufficient. Required.
+          */
         url: string;
+
+        /**
+          * The type of data you're expecting from the server. Defaults to json.
+          * @see http://api.jquery.com/jQuery.ajax/ for more info.
+          */
         dataType?: string;
+
+        /**
+          * Determines whether or not the browser will cache responses. 
+          * @see http://api.jquery.com/jQuery.ajax/ for more info.
+          */
         cache?: boolean;
+
+        /**
+          * Sets a timeout for requests.
+          * @see http://api.jquery.com/jQuery.ajax/ for more info.
+          */
         timeout?: number;
+
+        /**
+          * The pattern in url that will be replaced with the user's query 
+          * when a request is made. Defaults to %QUERY.
+          */
         wildcard?: string;
+
+        /**
+          * Overrides the request URL. If set, no wildcard substitution will 
+          * be performed on url.
+          * 
+          * @param url Replacement URL
+          * @param uriEncodedQuery Encoded query
+          * @returns A valid URL
+          */
         replace?: (url: string, uriEncodedQuery: string) => string;
-        rateLimitFn?: any; // debounce or trottle
+
+        /**
+          * The function used for rate-limiting network requests. 
+          * Can be either 'debounce' or 'throttle'. Defaults to 'debounce'.
+          */
+        rateLimitFn?: string;
+
+        /**
+          * The time interval in milliseconds that will be used by rateLimitFn. 
+          * Defaults to 300.
+          */
         rateLimitWait?: number;
+
+        /**
+          * The max number of parallel requests typeahead.js can have pending. 
+          * Defaults to 6.
+          */
         maxParallelRequests?: number;
+
+        /**
+          * A pre-request callback. Can be used to set custom headers.
+          * @see http://api.jquery.com/jQuery.ajax/ for more info.
+          */
         beforeSend?: (jqXhr: JQueryXHR, settings: JQueryAjaxSettings) => void;
+
+        /**
+          * Transforms the response body into an array of datums.
+          *
+          * @param parsedResponse Response body
+          */
         filter?: (parsedResponse: any) => Datum[];
     }
 
+    /**
+      * The individual units that compose datasets are called datums. 
+      * The canonical form of a datum is an object with a value property and 
+      * a tokens property. 
+      * 
+      * For ease of use, datums can also be represented as a string. 
+      * Strings found in place of datum objects are implicitly converted 
+      * to a datum object.
+      * 
+      * When datums are rendered as suggestions, the datum object is the 
+      * context passed to the template engine. This means if you include any 
+      * arbitrary properties in datum objects, those properties will be 
+      * available to the template used to render suggestions.
+      */
     interface Datum {
+        /** 
+          * The string that represents the underlying value of the datum 
+          */
         value: string;
+
+        /**
+          * A collection of single-word strings that aid typeahead.js in 
+          * matching datums with a given query.
+          */
         tokens: string[];
     }
-
-    interface TypeaheadStatic {
-        VERSION: string;
-        utils: TypeaheadUtils;
-    }
-
-    interface TypeaheadUtils {
-        debounce: (func: any, wait: number, immediate: boolean) => any;
-        throttle: (func: any, wait: number) => any;
-    }
 }
-
-interface JQuery {
-    /**
-      * Turns an input[type="text"] element into a typeahead.
-      *
-      * @constructor
-      * @param dataset Single dataset
-      */
-    typeahead(dataset: Twitter.Typeahead.Dataset): JQuery;
-
-    /**
-      * Turns an input[type="text"] element into a typeahead.
-      *
-      * @constructor
-      * @param dataset Array of datasets
-      */
-    typeahead(datasets: Twitter.Typeahead.Dataset[]): JQuery;
-
-    typeahead(methodName: string): JQuery;
-    typeahead(methodName: 'destroy'): JQuery;
-    typeahead(methodName: 'setQuery'): JQuery;
-}
-
-declare var typeahead: Twitter.Typeahead.TypeaheadStatic;