Document the vega module.

packages/vega/src/index.ts

@@ -1,3 +1,6 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
 import {
   JSONObject
 } from '@phosphor/coreutils';
@@ -18,31 +21,60 @@ import {
   DocumentRegistry
 } from '@jupyterlab/docregistry';
 
-
+/**
+ * Import vega-embed in this manner due to how it is exported.
+ */
 import embed = require('vega-embed');
 
 
-
+/**
+ * The CSS class to add to the Vega and Vega-Lite widget. 
+ */
 const VEGA_COMMON_CLASS = 'jp-RenderedVegaCommon';
 
+/**
+ * The CSS class to add to the Vega. 
+ */
 const VEGA_CLASS = 'jp-RenderedVega';
 
+/**
+ * The CSS class to add to the Vega-Lite. 
+ */
 const VEGALITE_CLASS = 'jp-RenderedVegaLite';
 
-
+/**
+ * The MIME type for Vega.
+ * 
+ * #### Notes
+ * The version of this follows the major version of Vega.
+ */
 export
 const VEGA_MIME_TYPE = 'application/vnd.vega.v2+json';
 
+/**
+ * The MIME type for Vega-Lite.
+ * 
+ * #### Notes
+ * The version of this follows the major version of Vega-Lite.
+ */
 export
 const VEGALITE_MIME_TYPE = 'application/vnd.vegalite.v1+json';
 
+
+/**
+ * A widget for rendering Vega or Vega-Lite data, for usage with rendermime.
+ */
 export
 class RenderedVega extends Widget {
-
+  /**
+   * Create a new widget for rendering Vega/Vega-Lite.
+   */
   constructor(options: RenderMime.IRenderOptions) {
     super();
     this.addClass(VEGA_COMMON_CLASS);
     this._model = options.model;
+
+    // Handle things related to the MIME type.
     let mimeType = this._mimeType = options.mimeType;
     if (mimeType === VEGA_MIME_TYPE) {
       this.addClass(VEGA_CLASS);
@@ -53,15 +85,24 @@ class RenderedVega extends Widget {
     }
   }
 
+  /**
+   * Dispose of the widget.
+   */
   dispose(): void {
     this._model = null;
     super.dispose();
   }
 
+  /**
+   * Trigger rendering after the widget is attached to the DOM.
+   */
   onAfterAttach(msg: Message): void {
     this._renderVega();
   }
 
+  /**
+   * Actual render Vega/Vega-Lite into this widget's node.
+   */
   private _renderVega(): void {
 
     let data = this._model.data.get(this._mimeType) as JSONObject;
@@ -88,7 +129,7 @@ class RenderedVega extends Widget {
 
 
 /**
- * A mime renderer for GeoJSON.
+ * A mime renderer for Vega/Vega-Lite data.
  */
 export
 class VegaRenderer implements RenderMime.IRenderer {
@@ -115,21 +156,41 @@ class VegaRenderer implements RenderMime.IRenderer {
    * Whether the renderer will sanitize the data given the render options.
    */
   wouldSanitize(options: RenderMime.IRenderOptions): boolean {
+    // TODO: Is this the correct logic?
     return !options.model.trusted;
   }
 }
 
 
+/**
+ * An interface for using a RenderMime.IRenderer for output and read-only documents.
+ */
 export
 interface IRendererExtension {
+  /**
+   * The MIME type for the renderer, which is the output MIME type it will handle.
+   */
   mimeType: string;
+
+  /**
+   * A renderer class to be registered to render the MIME type.
+   */
   renderer: RenderMime.IRenderer;
+
+  /**
+   * The index passed to `RenderMime.addRenderer`.
+   */
   rendererIndex?: number;
+
+  /**
+   * The options used for using the renderer for documents.
+   */
   widgetFactoryOptions: DocumentRegistry.IWidgetFactoryOptions;
 }
 
 
 const extensions: IRendererExtension | IRendererExtension[] = [
+  // Vega
   {
     mimeType: VEGA_MIME_TYPE,
     renderer: VegaRenderer,
@@ -141,6 +202,7 @@ const extensions: IRendererExtension | IRendererExtension[] = [
       readOnly: true
     }
   },
+  // Vega-Lite
   {
     mimeType: VEGALITE_MIME_TYPE,
     renderer: VegaRenderer,