add some js documentation (fixes #52

src/ts/define.ts

@@ -1,5 +1,6 @@
 // tslint:disable: object-literal-sort-keys
 
+/* Main commands, icons, and labels */
 export
 const COMMANDS = {
   // general

src/ts/main.ts

@@ -6,29 +6,38 @@ import {Browser, buildMenus, Header, Jobs, Notebooks, Reports, Status} from "./v
 
 export
 function main(): void {
+  /* show spinner to cover up page load */
   showLoader();
 
-  /* Title bar */
+  /* Title bar with logo and light/dark mode buttons */
   const header = new Header();
 
   /* main layout */
   // tslint:disable-next-line: no-shadowed-variable
   const main = new DockPanel();
   main.id = "main";
 
-  /* home browser */
+  /* Create Status page  */
   const status = new Status();
+  /* Create Notebooks page */
   const notebooks = new Notebooks(main, status);
+  /* Create Jobs page */
   const jobs = new Jobs(main, status);
+  /* Create Reports page */
   const reports = new Reports(main, status);
+  /* Create Search browser page */
   const browser = new Browser(notebooks, jobs, reports, status);
+
   browser.title.label = "Home";
   browser.title.closable = true;
+  /* Only show search by default, the rest are hidden in menus */
   main.addWidget(browser);
 
   /* File bar */
   const bar = new MenuBar();
   bar.id = "menuBar";
+
+  /* Build menu items out of main management tools */
   buildMenus(bar, {
     home: browser,
     jobs,
@@ -38,10 +47,14 @@ function main(): void {
     status,
   });
 
+  /* hook in window resize to top phosphor widget */
   window.onresize = () => { main.update(); };
 
+  /* Header */
   Widget.attach(header, document.body);
+  /* Menu bar */
   Widget.attach(bar, document.body);
+  /* Main dock panel with searchbar opened */
   Widget.attach(main, document.body);
 
   hideLoader(1000);

src/ts/utils/common.ts

@@ -1,6 +1,11 @@
 /*** Title Case formatter ***/
+/**
+ *
+ * @param str string to be converted to TitleCase
+ * @returns string in TitleCase
+ */
 export
-function toProperCase(str: string) {
+function toProperCase(str: string): string {
   return str.replace(/\w\S*/g,
     (txt: string) => {
       return txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase();

src/ts/utils/components/autocomplete.ts

@@ -1,7 +1,13 @@
 import {deleteAllChildren} from "../dom/index";
 import {IRequestResult, request} from "../request";
 
-/*** autocomplete key/name pairs from server ***/
+/**
+ * Helper function to autocomplete against a server endpoint and
+ * fill in a HTMLDataList
+ * @param path path to query server with partial entry
+ * @param value value representing the partial entry to autocomplete
+ * @param autocomplete HTMLDataListEleemnt to fill in with results
+ */
 export
 // tslint:disable-next-line: no-shadowed-variable
 function autocomplete(path: string, value: string, autocomplete: HTMLDataListElement) {
@@ -20,7 +26,12 @@ function autocomplete(path: string, value: string, autocomplete: HTMLDataListEle
     });
 }
 
-/*** build an autocomplete ***/
+/**
+ * Build an autocomplete searchbox
+ * @param name name of dom node
+ * @param url url to hit for reqults
+ * @param required is an entry required for the autocomplete input?
+ */
 export
 function buildAutocomplete(name: string, url: string, required= false): [HTMLInputElement, HTMLDataListElement] {
   const search = document.createElement("input");

src/ts/utils/components/detail.ts

@@ -3,7 +3,12 @@ import {IRequestResult, requestFormData} from "../request";
 import {createErrorDialog} from "./errors";
 import {createModal} from "./modal";
 
-/*** create detail view from python json response to detail ***/
+/**
+ * Helper function to create a detail view of an entry
+ * @param sec Phosphor widget in which to populate the results
+ * @param title title to give to table
+ * @param data JSON data representing the details
+ */
 export
 function createDetail(sec: HTMLFormElement, title: any, data: any): Promise<boolean> {
   return new Promise((resolve) => {
@@ -30,14 +35,21 @@ function createDetail(sec: HTMLFormElement, title: any, data: any): Promise<bool
   });
 }
 
-/*** create response modal from python json response to config ***/
+/**
+ * Helper function to create a global modal representing a response from the server
+ * (e.g. for successful form submission, error, etc)
+ * @param resp JSON response from server
+ */
 function createResponseModal(resp: [{[key: string]: string}]): Promise<boolean> {
   return new Promise((resolve) => {
     createModal(resp, true, false).then(resolve);
   });
 }
 
-/*** create request modal to ask "are you sure"? ***/
+/**
+ * Helper function to create a form confirmation modal prior to form submission
+ * (e.g. "Are you sure you want to save?")
+ */
 function createRequestModal(): Promise<boolean> {
   return new Promise((resolve) => {
     createModal([{type: "label", value: "Are you sure?"}], true, true).then((ok: boolean) => {

src/ts/utils/components/errors.ts

@@ -1,6 +1,10 @@
 import {IRequestResult} from "../request";
 import {createModal} from "./modal";
 
+/**
+ * Helper function to create an error modal
+ * @param res failed request response details
+ */
 export
 function createErrorDialog(res: IRequestResult): Promise<void> {
     return new Promise((resolve) => {

src/ts/utils/components/form.ts

@@ -2,7 +2,13 @@ import {buildVerticalTable} from "../dom/index";
 import {IRequestResult, requestFormData} from "../request";
 import {createModal} from "./modal";
 
-/*** create config from python json ***/
+/**
+ * Helper function to build a configuration editor into a vertical table
+ * @param sec form to put the config in
+ * @param clazz unused
+ * @param data JSON data to populate the form with
+ * @param callback callback on form submission (save/cancel)
+ */
 export
 function createConfigForm(sec: HTMLFormElement | null,
                           clazz: string,
@@ -26,7 +32,10 @@ return new Promise((resolve) => {
   });
 }
 
-/*** create response modal from python json response to config ***/
+/**
+ * Helper function to create a modal response from submission of the above form
+ * @param resp JSON data for response
+ */
 export
 function createResponseModal(resp: [{[key: string]: string}]): Promise<boolean> {
   return new Promise((resolve) => {

src/ts/utils/components/loader.ts

@@ -1,5 +1,9 @@
 export const loader = makeLoader();
 
+/**
+ * helper function to create global modal with a spinner in it
+ * Note: this is designed to be a singleton
+ */
 export
 function makeLoader(): HTMLDivElement {
   // tslint:disable-next-line: no-shadowed-variable
@@ -12,6 +16,10 @@ function makeLoader(): HTMLDivElement {
   return loader;
 }
 
+/**
+ * helper function to show global modal with spinner in it
+ * @param closeOnClick should we close the modal if the user clicks (for debug)
+ */
 export
 function showLoader(closeOnClick = false) {
   loader.style.display = "flex";
@@ -26,6 +34,10 @@ function showLoader(closeOnClick = false) {
   document.body.appendChild(loader);
 }
 
+/**
+ * Hide the global modal with spinner in it
+ * @param minload hide after minload milliseconds
+ */
 export
 function hideLoader(minload= 200) {
   setTimeout(() => {

src/ts/utils/components/modal.ts

@@ -1,8 +1,17 @@
 import {buildGeneric, deleteAllChildren} from "../dom/index";
 
+/**
+ * Only do this once to make sure its a singleton
+ */
 const modal = document.createElement("div");
 modal.classList.add("modal");
 
+/**
+ * Create the modal by clearing the previous modal and repopulate
+ * @param data JSON data to put into the modal
+ * @param ok show ok button?
+ * @param cancel show cancel button?
+ */
 export
 function createModal(data: Array<{[key: string]: string}>,
                      ok= true,
@@ -36,6 +45,9 @@ function createModal(data: Array<{[key: string]: string}>,
   });
 }
 
+/**
+ * helper function to hide the global modal
+ */
 export
 function hideModal(): Promise<void> {
     return new Promise((resolve) => {

src/ts/utils/components/primary.ts

@@ -2,7 +2,13 @@ import {PrimaryTab} from "../../views/index";
 import {buildListTable, deleteAllChildren} from "../dom/index";
 import {hideLoader, showLoader} from "./loader";
 
-/*** create paginated table from data ***/
+/**
+ * Create a primary section, which is a browser of all the available data
+ * @param widget PhosphorWidget to hold the primary data
+ * @param clazz class of the widget
+ * @param data JSON data from server with the data
+ * @param paginate helper function to paginate the data (if applicable)
+ */
 export
 function createPrimarySection(widget: PrimaryTab,
                               clazz: string,

src/ts/utils/components/status.ts

@@ -2,7 +2,12 @@ import {Widget} from "@phosphor/widgets";
 import {deleteAllChildren} from "../dom/common";
 import {buildHorizontalTable} from "../dom/horizontalTable";
 
-/*** create paginated table from data ***/
+/**
+ * Helper function to create status monitor table
+ * @param sec PhosphorWidget of the item we are monitoring status of
+ * @param clazz class of the widget
+ * @param data JSON data to populate the horizontal table
+ */
 export
 function createStatusSection(sec: Widget, clazz: string, data: any): void {
   const table = buildHorizontalTable(data);

src/ts/utils/dom/common.ts

@@ -1,5 +1,8 @@
 
-/*** delete all children of element helper ***/
+/**
+ * Helper to delete all children of a dom node
+ * @param element node to delete all children
+ */
 export
 function deleteAllChildren(element: HTMLElement): void {
   while (element.lastChild) {

src/ts/utils/dom/generic.ts

@@ -2,10 +2,16 @@ import {buildLabel} from "./label";
 
 // tslint:disable: no-empty
 
-/*** build a generic element ***/
+/**
+ * Helper utility to build generic dom nodes from server's json responses
+ * @param type type of element to build, usually a dom type
+ * @param content text content of element
+ * @param name name of element
+ */
 export
 function buildGeneric(type: string, content?: string, name?: string): HTMLElement {
   switch (type) {
+    /* Basic types are trivial, create the type and fill text content */
     case "br": {}
     case "span": {}
     case "p": {}
@@ -20,9 +26,11 @@ function buildGeneric(type: string, content?: string, name?: string): HTMLElemen
       d.textContent = content || "";
       return d;
     }
+    /* Label has a separate builder */
     case "label": {
       return buildLabel(content || "");
     }
+    /* Json we want to wrap it as a download link */
     case "json": {
       const a = document.createElement("a");
       a.download = "download.json";
@@ -32,6 +40,7 @@ function buildGeneric(type: string, content?: string, name?: string): HTMLElemen
       a.textContent = name || "Download";
       return a;
     }
+    /* ipynb we want to wrap as a download link */
     case "ipynb": {
       const a = document.createElement("a");
       a.download = "download.ipynb";
@@ -41,6 +50,7 @@ function buildGeneric(type: string, content?: string, name?: string): HTMLElemen
       a.textContent = name || "Download";
       return a;
     }
+    /* text we want to wrap as a download link */
     case "textfile": {
       if (content) {
         const a = document.createElement("a");

src/ts/utils/dom/horizontalTable.ts

@@ -1,5 +1,12 @@
 import {toProperCase} from "../index";
 
+/**
+ * Build a generic html table where data is displayed with
+ * keys in the top row and items in the rows beneath.
+ *
+ * Used in the status viewer.
+ * @param data JSON data to fill into table
+ */
 export
 function buildHorizontalTable(data: any): HTMLTableElement {
   const table = document.createElement("table");

src/ts/utils/dom/input.ts

@@ -1,7 +1,18 @@
 import {buildSelect} from "./select";
 import {buildTextarea} from "./textarea";
 
-/*** build an input ***/
+/**
+ * Helper function to build a generic input type
+ * @param type type of input, in <text, file, select, submit, etc..>
+ * @param name name of field for form submission
+ * @param placeholder text placeholder for field
+ * @param value initial/const value for field
+ * @param required is field required in form?
+ * @param readonly is field readonly in form?
+ * @param hidden is field hidden in form?
+ * @param options select input has a fixed set of choices
+ * @param json textarea can be unstructured or json
+ */
 export
 function buildInput(type?: string,
                     name?: string,

src/ts/utils/dom/label.ts

@@ -1,5 +1,8 @@
 
-/*** build a label ***/
+/**
+ * Helper function to build a generic label element
+ * @param text text to put in label
+ */
 export
 function buildLabel(text: string): HTMLLabelElement {
   const label = document.createElement("label");

src/ts/utils/dom/listTable.ts

@@ -1,6 +1,13 @@
 import {toProperCase} from "../index";
 import {buildGeneric} from "./generic";
 
+/**
+ * Helper function to build a variant of the Horizontal table.
+ *
+ * Used in the primary browsers.
+ * @param data JSON data to fill in the table
+ * @param ondblclick callback function when a row is double-clicked (e.g. display detail view for row)
+ */
 export
 function buildListTable(data: any,
                         // tslint:disable-next-line: no-empty

src/ts/utils/dom/select.ts

@@ -6,7 +6,14 @@ defaultNone.hidden = false;
 defaultNone.style.display = "none";
 defaultNone.value = "";
 
-/*** build a select ***/
+/**
+ * Helper function to build a select input element
+ * @param name name of select node for form
+ * @param list list of options to use for select
+ * @param def default option for select
+ * @param required is entry required for form submission?
+ * @param readonly is entry readonly?
+ */
 export
 function buildSelect(name: string,
                      list: string[],