Updated jsdocs for FlightBase.

flight/flight.d.ts

@@ -19,50 +19,52 @@ interface FlightComponent {
 
 interface FlightBase extends FlightAdvice, FlightComponent {
 
-	/**
-	 * Most Components and Mixins need to define attributes. In Flight, 
-	 * default values are assigned by passing an object to the defaultAttrs 
-	 * function.
-	 */
+    /**
+     * Most Components and Mixins need to define attributes. In Flight, 
+     * default values are assigned by passing an object to the defaultAttrs 
+     * function.
+     */
     defaultAttrs(obj: Object);
     
-	/**
-	 * The select method takes an attr key as its argument. The value of the 
-	 * attr must be a CSS Selector. The method will return all matching 
-	 * elements within the component's node.
-	 *
-	 * This is a handy alternative to jQuery's this.$node.find() and prevents 
-	 * accidental access to elements outside of the component's node.
-	 *
-	 * @param attr 
-	 */
+    /**
+     * The select method takes an attr key as its argument. The value of the 
+     * attr must be a CSS Selector. The method will return all matching 
+     * elements within the component's node.
+     *
+     * This is a handy alternative to jQuery's this.$node.find() and prevents 
+     * accidental access to elements outside of the component's node.
+     *
+     * @param attr 
+     */
     select(attr: string)
 
-	/**
-	 * This method is attached to the prototype of every Component; it accepts 
-	 * the component's node and an options object as arguments. The core 
-	 * implementation, which is called every time an instance is created, will
-	 * assign the node to the instance and override the default attrs with the 
-	 * options object.
-	 *
-	 * Components and Mixins will typically augment the core implementation by 
-	 * supplying a function as an argument to the after method (see the advice 
-	 * API for more information). This is a good place to set up event 
-	 * listeners that bind to callbacks.
-	 */
+    /**
+     * This method is attached to the prototype of every Component; it accepts 
+     * the component's node and an options object as arguments. The core 
+     * implementation, which is called every time an instance is created, will
+     * assign the node to the instance and override the default attrs with the 
+     * options object.
+     *
+     * Components and Mixins will typically augment the core implementation by 
+     * supplying a function as an argument to the after method (see the advice 
+     * API for more information). This is a good place to set up event 
+     * listeners that bind to callbacks.
+     */
     initialize();
 
-	/**
-	 * This allows a component instance to listen to an event and register a 
-	 * callback to be invoked. Flight will automatically bind the context 
-	 * (this) of the callback to the component instance.
-	 *
-	 * @param selector Optional. Specify the DOM node(s) that should listen for the event. Defaults to the component instance's node value.
-	 *
-	 * @param eventType The event type to listen for.
-	 *
-	 * @param handler Either a function (callback) to be invoked, or a map of targets and callbacks.
-	 */
+    /**
+     * This allows a component instance to listen to an event and register a 
+     * callback to be invoked. Flight will automatically bind the context 
+     * (this) of the callback to the component instance.
+     *
+     * @param selector Optional. Specify the DOM node(s) that should listen 
+	 *        for the event. Defaults to the component instance's node value.
+     *
+     * @param eventType The event type to listen for.
+     *
+     * @param handler Either a function (callback) to be invoked, or a map of 
+	 *        targets and callbacks.
+     */
     on(eventType: string, handler: Function);
     on(selector: string, eventType: string, handler: Function);
     on(selector: Document, eventType: string, handler: Function);
@@ -73,6 +75,18 @@ interface FlightBase extends FlightAdvice, FlightComponent {
     on(selector: Element, eventType: string, handler: Object);
     on(selector: Element[], eventType: string, handler: Object);
 
+    /**
+     * If we no longer want a component instance to listen to an event we can 
+     * use the off method to unsubscribe.
+     *
+     * @param selector Optional. The DOM node(s) listening for the event. 
+     *        Defaults to the component instance's node value.
+     *
+     * @param eventType The event type being listened to.
+     *
+     * @param handler Optional. The function (callback) to detach from the 
+     *        component instance. Defaults to the detaching all callbacks for the event.
+	 */
     off(eventType: string, handler?: Function);
     off(selector: string, eventType: string, handler?: Function);
     off(selector: Document, eventType: string, handler?: Function);
@@ -91,6 +105,25 @@ interface FlightBase extends FlightAdvice, FlightComponent {
     off(selector: Element, eventType: Object, handler?: Object);
     off(selector: Element[], eventType: Object, handler?: Object);
 
+    /**
+     * Trigger an event.
+     *
+     * @param selector Optional. The DOM node(s) that the event will be 
+     *        dispatched to. Defaults to the component instance's node value.
+     *
+     * @param eventType String. The event type to be triggered.
+     *
+     * You can also specify a default function that will be called by the 
+     * component, providing that nothing in the event's bubble chain invokes 
+     * preventDefault. Default functions in custom events are analagous to the 
+     * default actions of native events.
+     *
+     * To define a default function, make the eventType argument an object 
+     * that specifies the event's type and a defaultBehavior property. A 
+     * common use case is defining default behavior for keyboard events.
+     *
+     * @param eventPayload This is the payload of data that accompanies the event.
+     */
     trigger(eventType: string);
     trigger(selector: string, eventType: string, eventPayload?: Object);
     trigger(selector: Document, eventType: string, eventPayload?: Object);
@@ -102,6 +135,14 @@ interface FlightBase extends FlightAdvice, FlightComponent {
     trigger(selector: Element, eventType: Object, eventPayload?: Object);
     trigger(selector: Element[], eventType: Object, eventPayload?: Object);
 
+    /**
+     * Remove a component instance and its event bindings.
+     *
+     * It's a good idea to teardown components after each unit test - and 
+     * teardown is also good for unbinding event listeners when, for example, 
+     * the user navigates away from a page.
+     *
+     */
     teardown();
 }