grainjs 1.0.2 → 1.1.0

package/lib/domMethods.ts

@@ -12,9 +12,9 @@ import {G} from './browserGlobals';
 const _dataMap: WeakMap<Node, {[key: string]: any}> = new WeakMap();
 
 /**
- * Sets multiple attributes of a DOM element. The `attrs()` variant takes no `elem` argument.
+ * Sets multiple attributes of a DOM element.
  * Null and undefined values are omitted, and booleans are either omitted or set to empty string.
- * @param {Object} attrsObj: Object mapping attribute names to attribute values.
+ * @param attrsObj - Object mapping attribute names to attribute values.
  */
 export function attrsElem(elem: Element, attrsObj: IAttrObj): void {
   for (const key of Object.keys(attrsObj)) {
@@ -24,53 +24,74 @@ export function attrsElem(elem: Element, attrsObj: IAttrObj): void {
     }
   }
 }
+
+/**
+ * Sets multiple attributes of a DOM element. Null and undefined values are omitted, and booleans
+ * are either omitted or set to empty string.
+ */
 export function attrs(attrsObj: IAttrObj): DomElementMethod {
   return (elem) => attrsElem(elem, attrsObj);
 }
 
 /**
  * Sets an attribute of a DOM element to the given value. Removes the attribute when the value is
- * null or undefined. The `attr()` variant takes no `elem` argument, and `attrValue` may be an
- * observable or function.
- * @param {Element} elem: The element to update.
- * @param {String} attrName: The name of the attribute to bind, e.g. 'href'.
- * @param {String|null} attrValue: The string value or null to remove the attribute.
+ * null or undefined.
+ * @param elem - The element to update.
+ * @param attrName - The name of the attribute to bind, e.g. 'href'.
+ * @param attrValue - The string value, or null or undefined to remove the attribute.
  */
-export function attrElem(elem: Element, attrName: string, attrValue: string|null): void {
+export function attrElem(elem: Element, attrName: string, attrValue: string|null|undefined): void {
   if (attrValue === null || attrValue === undefined) {
     elem.removeAttribute(attrName);
   } else {
     elem.setAttribute(attrName, attrValue);
   }
 }
-export function attr(attrName: string, attrValueObs: BindableValue<string>): DomElementMethod {
+
+/**
+ * Sets an attribute of a DOM element to the given value. Removes the attribute when the value is
+ * null or undefined.
+ *
+ * @example
+ * ```ts
+ * dom('a', dom.attr('href', urlObs))
+ * ```
+ */
+export function attr(attrName: string, attrValueObs: BindableValue<string|null|undefined>): DomElementMethod {
   return (elem) => _subscribe(elem, attrValueObs, (val) => attrElem(elem, attrName, val));
 }
 
 /**
  * Sets or removes a boolean attribute of a DOM element. According to the spec, empty string is a
  * valid true value for the attribute, and the false value is indicated by the attribute's absence.
- * The `boolAttr()` variant takes no `elem`, and `boolValue` may be an observable or function.
- * @param {Element} elem: The element to update.
- * @param {String} attrName: The name of the attribute to bind, e.g. 'checked'.
- * @param {Boolean} boolValue: Boolean value whether to set or unset the attribute.
+ * @param elem - The element to update.
+ * @param attrName - The name of the attribute to bind, e.g. 'checked'.
+ * @param boolValue - Boolean value whether to set or unset the attribute.
  */
 export function boolAttrElem(elem: Element, attrName: string, boolValue: boolean): void {
   attrElem(elem, attrName, boolValue ? '' : null);
 }
+/**
+ * Dom-method that sets or removes a boolean attribute of a DOM element.
+ * @param attrName - The name of the attribute to bind, e.g. 'checked'.
+ * @param boolValueObs - Value, observable, or function for a whether to set or unset the attribute.
+ */
 export function boolAttr(attrName: string, boolValueObs: BindableValue<boolean>): DomElementMethod {
   return (elem) => _subscribe(elem, boolValueObs, (val) => boolAttrElem(elem, attrName, val));
 }
 
 /**
- * Adds a text node to the element. The `text()` variant takes no `elem`, and `value` may be an
- * observable or function.
- * @param {Element} elem: The element to update.
- * @param {String} value: The text value to add.
+ * Adds a text node to the element.
+ * @param elem - The element to update.
+ * @param value - The text value to add.
  */
 export function textElem(elem: Node, value: string): void {
   elem.appendChild(G.document.createTextNode(value));
 }
+
+/**
+ * Sets text content of a DOM element to a value that may be an observable or a function.
+ */
 export function text(valueObs: BindableValue<string>): DomMethod {
   return (elem) => {
     const textNode = G.document.createTextNode('');
@@ -80,15 +101,21 @@ export function text(valueObs: BindableValue<string>): DomMethod {
 }
 
 /**
- * Sets a style property of a DOM element to the given value. The `style()` variant takes no
- * `elem`, and `value` may be an observable or function.
- * @param {Element} elem: The element to update.
- * @param {String} property: The name of the style property to update, e.g. 'fontWeight'.
- * @param {String} value: The value for the property.
+ * Sets a style property of a DOM element to the given value.
+ * @param elem - The element to update.
+ * @param property - The name of the style property to update, e.g. 'fontWeight'.
+ * @param value - The value for the property.
  */
 export function styleElem(elem: Element, property: string, value: string): void {
   (elem as any).style[property] = value;
 }
+
+/**
+ * Sets a style property of a DOM element to the given value, which may be an observable or a
+ * function.
+ * @param property - The name of the style property to update, e.g. 'fontWeight'.
+ * @param value - The value for the property.
+ */
 export function style(property: string, valueObs: BindableValue<string>): DomElementMethod {
   return (elem) =>
     _subscribe(elem, valueObs, (val) => styleElem(elem, property, val));
@@ -96,14 +123,20 @@ export function style(property: string, valueObs: BindableValue<string>): DomEle
 
 /**
  * Sets the property of a DOM element to the given value.
- * The `prop()` variant takes no `elem`, and `value` may be an observable or function.
- * @param {Element} elem: The element to update.
- * @param {String} property: The name of the property to update, e.g. 'disabled'.
- * @param {Object} value: The value for the property.
+ * @param elem - The element to update.
+ * @param property - The name of the property to update, e.g. 'disabled'.
+ * @param value - The value for the property.
  */
 export function propElem<T>(elem: Node, property: string, value: T): void {
   (elem as any)[property] = value;
 }
+
+/**
+ * Sets the property of a DOM element to the given value, which may be an observable or a
+ * function.
+ * @param property - The name of the property to update, e.g. 'disabled'.
+ * @param value - The value for the property.
+ */
 export function prop<T>(property: string, valueObs: BindableValue<T>): DomMethod {
   return (elem) => _subscribe(elem, valueObs, (val) => propElem(elem, property, val));
 }
@@ -111,13 +144,17 @@ export function prop<T>(property: string, valueObs: BindableValue<T>): DomMethod
 /**
  * Shows or hides the element depending on a boolean value. Note that the element must be visible
  * initially (i.e. unsetting style.display should show it).
- * The `show()` variant takes no `elem`, and `boolValue` may be an observable or function.
- * @param {Element} elem: The element to update.
- * @param {Boolean} boolValue: True to show the element, false to hide it.
+ * @param elem - The element to update.
+ * @param boolValue - True to show the element, false to hide it.
  */
 export function showElem(elem: HTMLElement, boolValue: boolean): void {
   elem.style.display = boolValue ? '' : 'none';
 }
+
+/**
+ * Shows or hides the element depending on a boolean value, which may be an observable or a function.
+ * Note that the element must be visible by default (i.e. unsetting `style.display` should show it).
+ */
 export function show(boolValueObs: BindableValue<boolean>): DomElementMethod {
   return (elem) =>
     _subscribe(elem, boolValueObs, (val) => showElem(elem, val));
@@ -125,13 +162,18 @@ export function show(boolValueObs: BindableValue<boolean>): DomElementMethod {
 
 /**
  * The opposite of show, hiding the element when boolValue is true.
- * The `hide()` variant takes no `elem`, and `boolValue` may be an observable or function.
- * @param {Element} elem: The element to update.
- * @param {Boolean} boolValue: True to hide the element, false to show it.
+ * @param elem - The element to update.
+ * @param boolValue - True to hide the element, false to show it.
  */
 export function hideElem(elem: HTMLElement, boolValue: boolean): void {
   elem.style.display = boolValue ? 'none' : '';
 }
+
+/**
+ * The opposite of show, hiding the element when boolValue is true. `boolValueObs` may be an
+ * observable or a function.
+ * Note that the element must be visible by default (i.e. unsetting `style.display` should show it).
+ */
 export function hide(boolValueObs: BindableValue<boolean>): DomElementMethod {
   return (elem) =>
     _subscribe(elem, boolValueObs, (val) => hideElem(elem, val));
@@ -148,12 +190,13 @@ export function clsElem(elem: Element, className: string, boolValue: boolean = t
  * Sets or toggles a css class className. If className is an observable, it will be replaced when
  * the observable changes. If a plain string, then an optional second boolean observable may be
  * given, which will toggle it.
- *
- *    dom.cls('foo')                                // Sets className 'foo'
- *    dom.cls('foo', isFoo);                        // Toggles 'foo' className according to observable.
- *    dom.cls('foo', (use) => use(isFoo));          // Toggles 'foo' className according to observable.
- *    dom.cls(fooClass);                            // Sets className to the value of fooClass observable
- *    dom.cls((use) => `prefix-${use(fooClass)}`);  // Sets className to prefix- plus fooClass observable.
+ * ```ts
+ * dom.cls('foo')                                // Sets className 'foo'
+ * dom.cls('foo', isFoo);                        // Toggles 'foo' className according to observable.
+ * dom.cls('foo', (use) => use(isFoo));          // Toggles 'foo' className according to observable.
+ * dom.cls(fooClass);                            // Sets className to the value of fooClass observable
+ * dom.cls((use) => `prefix-${use(fooClass)}`);  // Sets className to prefix- plus fooClass observable.
+ * ```
  */
 export function cls(className: string, boolValue?: BindableValue<boolean>): DomElementMethod;
 export function cls(className: BindableValue<string>): DomElementMethod;
@@ -193,11 +236,10 @@ function _clsDynamicPrefix(prefix: string, className: BindableValue<string>): Do
 }
 
 /**
- * Associate arbitrary data with a DOM element. The `data()` variant takes no `elem`, and `value`
- * may be an observable or function.
- * @param {Element} elem: The element with which to associate data.
- * @param {String} key: Key to identify this piece of data among others attached to elem.
- * @param {Object} value: Arbitrary value to associate with elem.
+ * Associate arbitrary data with a DOM element.
+ * @param elem - The element with which to associate data.
+ * @param key - Key to identify this piece of data among others attached to elem.
+ * @param value - Arbitrary value to associate with elem.
  */
 export function dataElem(elem: Node, key: string, value: any): void {
   const obj = _dataMap.get(elem);
@@ -208,9 +250,19 @@ export function dataElem(elem: Node, key: string, value: any): void {
     _dataMap.set(elem, {[key]: value});
   }
 }
+
+/**
+ * Associate arbitrary data with a DOM element: `value` may be an observable or a function.
+ * @param key - Key to identify this piece of data among others attached to elem.
+ * @param value - Arbitrary value to associate with elem.
+ */
 export function data(key: string, valueObs: BindableValue<any>): DomMethod {
   return (elem) => _subscribe(elem, valueObs, (val) => dataElem(elem, key, val));
 }
+
+/**
+ * Retrieve data associated with a DOM element using `data()` or `dataElem()`.
+ */
 export function getData(elem: Node, key: string) {
   const obj = _dataMap.get(elem);
   return obj && obj[key];
@@ -219,7 +271,7 @@ export function getData(elem: Node, key: string) {
 /**
  * A very simple setup to identify DOM elements for testing purposes. Here's the recommended
  * usage.
- *
+ * ```ts
  *   // In the component to be tested.
  *   import {noTestId, TestId} from 'grainjs';
  *
@@ -228,17 +280,20 @@ export function getData(elem: Node, key: string) {
  *       dom(..., testId("another-name"), ...),
  *     );
  *   }
+ * ```
  *
  * In the fixture code using this component:
- *
+ * ```ts
  *   import {makeTestId} from 'grainjs';
  *
  *   dom(..., myComponent(myArgs, makeTestId('test-mycomp-'), ...)
+ * ```
  *
  * In the webdriver test code:
- *
+ * ```ts
  *   driver.find('.test-my-comp-some-name')
  *   driver.find('.test-my-comp-another-name')
+ * ```
  *
  * When myComponent() is created with testId argument omitted, the testId() calls are no-ops. When
  * makeTestId('test-foo-') is passed in, testId() calls simply add a css class with that prefix.

package/lib/domevent.ts

@@ -1,44 +1,3 @@
-/**
- * domevent provides a way to listen to DOM events, similar to JQuery's `on()` function. Its
- * methods are also exposed via the dom.js module, as `dom.on()`, etc.
- *
- * It is typically used as an argument to the dom() function:
- *
- *    dom('div', dom.on('click', (event, elem) => { ... }));
- *
- * When the div is disposed, the listener is automatically removed.
- *
- * The underlying interface to listen to an event is this:
- *
- *    let listener = dom.onElem(elem, 'click', (event, elem) => { ... });
- *
- * The callback is called with the event and the element to which it was attached. Unlike in
- * JQuery, the callback's return value is ignored. Use event.stopPropagation() and
- * event.preventDefault() explicitly if needed.
- *
- * To stop listening:
- *
- *    listener.dispose();
- *
- * Disposing the listener returned by .onElem() is the only way to stop listening to an event. You
- * can use autoDispose to stop listening automatically when subscribing in a Disposable object:
- *
- *    this.autoDispose(domevent.onElem(document, 'mouseup', callback));
- *
- * To listen to descendants of an element matching the given selector (what JQuery calls
- * "delegated events", see http://api.jquery.com/on/):
- *
- *    dom('div', dom.onMatch('.selector', 'click', (event, elem) => { ... }));
- * or
- *    let lis = domevent.onMatchElem(elem, '.selector', 'click', (event, el) => { ... });
- *
- * In this usage, the element passed to the callback will be a DOM element matching the given
- * selector. If there are multiple matches, the callback is only called for the innermost one.
- *
- * If you need to remove the callback on first call, here's a useful pattern:
- *    let lis = domevent.onElem(elem, 'mouseup', e => { lis.dispose(); other_work(); });
- */
-
 import {IDisposable} from './dispose';
 import {DomElementMethod, DomMethod} from './domImpl';
 
@@ -87,20 +46,59 @@ class DomEventMatchListener<E extends Event> extends DomEventListener<E, EventTa
 }
 
 /**
- * Listen to a DOM event. The `on()` variant takes no `elem` argument, and may be used as an
- * argument to dom() function.
- * @param {DOMElement} elem: DOM Element to listen to.
- * @param {String} eventType: Event type to listen for (e.g. 'click').
- * @param {Function} callback: Callback to call as `callback(event, elem)`, where elem is `elem`.
- * @param [Boolean] options.useCapture: Add the listener in the capture phase. This should very
+ * Listen to a DOM event, returning the listener object.
+ * ```ts
+ * const listener = dom.onElem(elem, 'click', (event, elem) => { ... });
+ * ```
+ *
+ * To stop listening:
+ * ```ts
+ * listener.dispose();
+ * ```
+ *
+ * Disposing the listener returned by `onElem()` is the only way to stop listening to an event. You
+ * can use `autoDispose` to stop listening automatically when subscribing in a `Disposable` object:
+ * ```ts
+ * this.autoDispose(domevent.onElem(document, 'mouseup', callback));
+ * ```
+ *
+ * If you need "once" semantics, i.e. to remove the callback on first call, here's a useful pattern:
+ * ```ts
+ * const lis = domevent.onElem(elem, 'mouseup', e => { lis.dispose(); other_work(); });
+ * ```
+ *
+ * @param elem - DOM Element to listen to.
+ * @param eventType - Event type to listen for (e.g. `'click'`).
+ * @param callback - Callback to call as `callback(event, elem)`, where elem is `elem`.
+ * @param options - `useCapture: boolean`: Add the listener in the capture phase. This should very
  *    rarely be useful (e.g. JQuery doesn't even offer it as an option).
- * @returns {Object} Listener object whose .dispose() method will remove the event listener.
+ * @returns Listener object whose `.dispose()` method will remove the event listener.
  */
 export function onElem<E extends EventName|string, T extends EventTarget>(
   elem: T, eventType: E, callback: EventCB<EventType<E>, T>, {useCapture = false} = {}): IDisposable {
   return new DomEventListener(elem, eventType, callback, useCapture);
 }
 
+/**
+ * Listen to a DOM event. It is typically used as an argument to the `dom()` function:
+ * ```ts
+ * dom('div', dom.on('click', (event, elem) => { ... }));
+ * ```
+ *
+ * When the div is disposed, the listener is automatically removed.
+ *
+ * The callback is called with the event and the element to which it was attached. Unlike in, say,
+ * JQuery, the callback's return value is ignored. Use `event.stopPropagation()` and
+ * `event.preventDefault()` explicitly if needed.
+ *
+ * To listen to descendants of an element matching the given selector (what JQuery calls
+ * "delegated events", see http://api.jquery.com/on/), see [`onMatch`](#onMatch).
+ *
+ * @param eventType - Event type to listen for (e.g. `'click'`).
+ * @param callback - Callback to call as `callback(event, elem)`, where `elem` is the element this
+ *    listener is attached to.
+ * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
+ */
 export function on<E extends EventName|string, T extends EventTarget>(
   eventType: E, callback: EventCB<EventType<E>, T>, {useCapture = false} = {}): DomMethod<T> {
   // tslint:disable-next-line:no-unused-expression
@@ -108,24 +106,46 @@ export function on<E extends EventName|string, T extends EventTarget>(
 }
 
 /**
- * Listen to a DOM event on descendants of the given elem matching the given selector. The
- * `onMatch()` variant takes no `elem` argument, and may be used as an argument to dom().
- * @param {DOMElement} elem: DOM Element to whose descendants to listen.
- * @param {String} selector: CSS selector string to filter elements that trigger this event.
+ * Listen to a DOM event on descendants of the given elem matching the given selector.
+ *
+ * ```ts
+ * const let lis = domevent.onMatchElem(elem, '.selector', 'click', (event, el) => { ... });
+ * ```
+ *
+ * @param elem - DOM Element to whose descendants to listen.
+ * @param selector - CSS selector string to filter elements that trigger this event.
  *    JQuery calls it "delegated events" (http://api.jquery.com/on/). The callback will only be
  *    called when the event occurs for an element matching the given selector. If there are
  *    multiple elements matching the selector, the callback is only called for the innermost one.
- * @param {String} eventType: Event type to listen for (e.g. 'click').
- * @param {Function} callback: Callback to call as `callback(event, elem)`, where elem is a
+ * @param eventType - Event type to listen for (e.g. 'click').
+ * @param callback - Callback to call as `callback(event, elem)`, where elem is a
  *    descendent of `elem` which matches `selector`.
- * @param [Boolean] options.useCapture: Add the listener in the capture phase. This should very
- *    rarely be useful (e.g. JQuery doesn't even offer it as an option).
- * @returns {Object} Listener object whose .dispose() method will remove the event listener.
+ * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
+ * @returns Listener object whose `.dispose()` method will remove the event listener.
  */
 export function onMatchElem(elem: EventTarget, selector: string, eventType: string,
                             callback: EventCB, {useCapture = false} = {}): IDisposable {
   return new DomEventMatchListener(elem, eventType, callback, useCapture, selector);
 }
+
+/**
+ * Listen to a DOM event on descendants of the given element matching the given selector.
+ *
+ * This is similar to JQuery's [delegated events](https://api.jquery.com/on/#direct-and-delegated-events)
+ *
+ * ```ts
+ * dom('div', dom.onMatch('.selector', 'click', (event, elem) => { ... }));
+ * ```
+ *
+ * In this usage, the element passed to the callback will be a DOM element matching the given
+ * selector. If there are multiple matches, the callback is only called for the innermost one.
+ *
+ * @param selector - CSS selector string to filter elements that trigger this event.
+ * @param eventType - Event type to listen for (e.g. `'click'`).
+ * @param callback - Callback to call as `callback(event, elem)`, where `elem` is an element
+ *    matching `selector`.
+ * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
+ */
 export function onMatch(selector: string, eventType: string, callback: EventCB,
                         {useCapture = false} = {}): DomElementMethod {
   // tslint:disable-next-line:no-unused-expression
@@ -142,8 +162,6 @@ export interface IKeyHandlers<T extends HTMLElement = HTMLElement> {
  * Listen to key events (typically 'keydown' or 'keypress'), with specified per-key callbacks.
  * Key names are listed at https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values
  *
- * Methods onKeyPress() and onKeyDown() are intended to be used as arguments to dom().
- *
  * By default, handled events are stopped from bubbling with stopPropagation() and
  * preventDefault(). If, however, you register a key with a "$" suffix (i.e. "Enter$" instead of
  * "Enter"), then the event is allowed to bubble normally.
@@ -152,7 +170,7 @@ export interface IKeyHandlers<T extends HTMLElement = HTMLElement> {
  * to allow this element to receive keyboard events.
  *
  * For example:
- *
+ * ```
  *    dom('input', ...
  *      dom.onKeyDown({
  *        Enter: (e, elem) => console.log("Enter pressed"),
@@ -160,6 +178,7 @@ export interface IKeyHandlers<T extends HTMLElement = HTMLElement> {
  *        Delete$: (e, elem) => console.log("Delete pressed, will bubble"),
  *      })
  *    )
+ * ```
  */
 export function onKeyElem<T extends HTMLElement>(
   elem: T, evType: KeyEventType, keyHandlers: IKeyHandlers<T>,
@@ -180,10 +199,16 @@ export function onKeyElem<T extends HTMLElement>(
   });
 }
 
+/**
+ * Add listeners to `"keypress"` events. See [`onKeyElem`](#onKeyElem) for details.
+ */
 export function onKeyPress<T extends HTMLElement>(keyHandlers: IKeyHandlers<T>): DomMethod<T> {
   return (elem) => { onKeyElem(elem, 'keypress', keyHandlers); };
 }
 
+/**
+ * Add listeners to `"keydown"` events. See [`onKeyElem`](#onKeyElem) for details.
+ */
 export function onKeyDown<T extends HTMLElement>(keyHandlers: IKeyHandlers<T>): DomMethod<T> {
   return (elem) => { onKeyElem(elem, 'keydown', keyHandlers); };
 }

package/lib/emit.ts

@@ -1,48 +1,16 @@
-/**
- * emit.js implements an Emitter class which emits events to a list of listeners. Listeners are
- * simply functions to call, and "emitting an event" just calls those functions.
- *
- * This is similar to Backbone events, with more focus on efficiency. Both inserting and removing
- * listeners is constant time.
- *
- * To create an emitter:
- *    let emitter = new Emitter();
- *
- * To add a listener:
- *    let listener = fooEmitter.addListener(callback);
- * To remove a listener:
- *    listener.dispose();
- *
- * The only way to remove a listener is to dispose the Listener object returned by addListener().
- * You can often use autoDispose to do this automatically when subscribing in a constructor:
- *    this.autoDispose(fooEmitter.addListener(this.onFoo, this));
- *
- * To emit an event, call emit() with any number of arguments:
- *    emitter.emit("hello", "world");
- */
-
-// Note about a possible alternative implementation.
-//
-// We could implement the same interface using an array of listeners. Certain issues apply, in
-// particular with removing listeners from inside emit(), and in ensuring that removals are
-// constant time on average. Such an implementation was attempted and timed. The result is that
-// compared to the linked-list implementation here, add/remove combination could be made nearly
-// twice faster (on average), while emit and add/remove/emit are consistently slightly slower.
-//
-// The implementation here was chosen based on those timings, and as the simpler one. For example,
-// on one setup (macbook, node4, 5-listener queue), add+remove take 0.1us, while add+remove+emit
-// take 3.82us. (In array-based implementation with same set up, add+remove is 0.06us, while
-// add+remove+emit is 4.80us.)
-
-// The private property name to hold next/prev pointers.
-
 function _noop() { /* noop */}
 
 export type ListenerCB<T> = (this: T, ...args: any[]) => void;
+
+/**
+ * A callback that listens to _changes_ in the Emitter listeners. This is mainly used for
+ * internal purposes.
+ */
 export type ChangeCB = (hasListeners: boolean) => void;
 
 /**
  * This is an implementation of a doubly-linked list, with just the minimal functionality we need.
+ * @internal
  */
 export class LLink {
   protected _next: LLink|null = null;
@@ -76,7 +44,7 @@ export class LLink {
   }
 
   protected _disposeList(): void {
-    let node: LLink = this;
+    let node: LLink = this;     // eslint-disable-line @typescript-eslint/no-this-alias
     let next = node._next;
     while (next !== null) {
       node._next = node._prev = null;
@@ -86,20 +54,63 @@ export class LLink {
   }
 }
 
+/**
+ * An `Emitter` emits events to a list of listeners. Listeners are
+ * simply functions to call, and "emitting an event" just calls those functions.
+ *
+ * This is similar to Backbone events, with more focus on efficiency. Both inserting and removing
+ * listeners is constant time.
+ *
+ * To create an emitter:
+ * ```ts
+ * const emitter = new Emitter();
+ * ```
+ *
+ * To add a listener:
+ * ```ts
+ * const listener = fooEmitter.addListener(callback);
+ * ```
+ *
+ * To remove a listener:
+ * ```ts
+ * listener.dispose();
+ * ```
+ *
+ * The only way to remove a listener is to dispose the `Listener` object returned by `addListener()`.
+ * You can often use autoDispose to do this automatically when subscribing in a constructor:
+ * ```ts
+ * this.autoDispose(fooEmitter.addListener(this.onFoo, this));
+ * ```
+ *
+ * To emit an event, call `emit()` with any number of arguments:
+ * ```ts
+ * emitter.emit("hello", "world");
+ * ```
+ *
+ * @privateRemarks
+ *
+ * Note about a possible alternative implementation.
+ *
+ * We could implement the same interface using an array of listeners. Certain issues apply, in
+ * particular with removing listeners from inside emit(), and in ensuring that removals are
+ * constant time on average. Such an implementation was attempted and timed. The result is that
+ * compared to the linked-list implementation here, add/remove combination could be made nearly
+ * twice faster (on average), while emit and add/remove/emit are consistently slightly slower.
+ *
+ * The implementation here was chosen based on those timings, and as the simpler one. For example,
+ * on one setup (macbook, node4, 5-listener queue), add+remove take 0.1us, while add+remove+emit
+ * take 3.82us. (In array-based implementation with same set up, add+remove is 0.06us, while
+ * add+remove+emit is 4.80us.)
+ */
 export class Emitter extends LLink {
   private _changeCB: ChangeCB = _noop;
   private _changeCBContext: any = undefined;
 
-  /**
-   * Constructs an Emitter object.
-   */
-  constructor() { super(); }
-
   /**
    * Adds a listening callback to the list of functions to call on emit().
-   * @param {Function} callback: Function to call.
-   * @param {Object} optContext: Context for the function.
-   * @returns {Listener} Listener object. Its dispose() method removes the callback from the list.
+   * @param callback - Function to call.
+   * @param optContext - Context for the function.
+   * @returns Listener object. Its dispose() method removes the callback from the list.
    */
   public addListener<T>(callback: ListenerCB<T>, optContext?: T): Listener {
     return new Listener(this, callback, optContext);
@@ -114,7 +125,7 @@ export class Emitter extends LLink {
 
   /**
    * Sets the single callback that would get called when a listener is added or removed.
-   * @param {Function} changeCB(hasListeners): Function to call after a listener is added or
+   * @param changeCB - Function to call after a listener is added or
    *    removed. It's called with a boolean indicating whether this Emitter has any listeners.
    *    Pass in `null` to unset the callback. Note that it can be called multiple times in a row
    *    with hasListeners `true`.
@@ -126,6 +137,7 @@ export class Emitter extends LLink {
 
   /**
    * Helper used by Listener class, but not intended for public usage.
+   * @internal
    */
   public _triggerChangeCB(): void {
     this._changeCB.call(this._changeCBContext, this.hasListeners());
@@ -150,10 +162,11 @@ export class Emitter extends LLink {
 }
 
 /**
- * Listener object wraps a callback added to an Emitter, allowing for O(1) removal when the
- * listener is disposed.
+ * The `Listener` object wraps a callback added to an Emitter, allowing for O(1) removal when the
+ * listener is disposed. It implements `IDisposable`.
  */
 export class Listener extends LLink {
+  /** @internal */
   public static callAll(begin: LLink, end: LLink, args: any[]): void {
     while (begin !== end) {
       const lis = begin as Listener;
@@ -170,6 +183,7 @@ export class Listener extends LLink {
     emitter._triggerChangeCB();
   }
 
+  /** @internal */
   public dispose(): void {
     if (this.isDisposed()) { return; }
     this._removeNode(this);