Add JSDoc to components and services

Bug: 193062584
Bug: 193437013
Change-Id: Ia016228ba9811e499aace074e30788a4bd9c706d

Author: Fleker

src/app/app.component.ts

@@ -19,6 +19,9 @@ import {MatTabChangeEvent} from '@angular/material/tabs';
 import {ChromeBridgeService} from './chrome-bridge.service';
 import {PreferencesService} from './preferences.service';
 
+/**
+ * Primary component that encompasses the Chrome Extension.
+ */
 @Component({
   selector: 'app-root',
   templateUrl: './app.component.html',
@@ -37,6 +40,12 @@ export class AppComponent {
     this.preferences = preferences;
   }
 
+  /**
+   * Event that executes when the selected tab changes. This can be used to
+   * pull or push data between the extension and client. Currently it will
+   * re-fetch the Interactive Canvas app history.
+   * @param event Generated event on each tab change
+   */
   async tabChanged(event: MatTabChangeEvent) {
     const {index} = event;
     const debugExtension = await this.preferences.getFlagDebugExtension();

src/app/preferences.service.ts

@@ -19,7 +19,6 @@ import {Injectable} from '@angular/core';
 
 /**
  * Every setting should have getters/setters that work with Chrome storage API.
- * See https://developer.chrome.com/docs/extensions/reference/storage/
  */
 interface ExtensionPreferences {
   /**
@@ -34,6 +33,12 @@ interface ExtensionPreferences {
 
 type ExtensionPreference = keyof ExtensionPreferences;
 
+/**
+ * The Preferences service manages extension-wide preferences in a persistent
+ * manner. It synchronizes changes with the browser preferences so that
+ * they persist between sessions and between browser instances.
+ * @see https://developer.chrome.com/docs/extensions/reference/storage/
+ */
 @Injectable({
   providedIn: 'root',
 })

src/app/tab-history/tab-history.component.ts

@@ -36,6 +36,12 @@ interface SortedCanvasHistory extends CanvasHistory {
   relativeTime: string;
 }
 
+/**
+ * The History tab displays a record of outbound Interactive Canvas
+ * events and displays them in chronological order starting from the
+ * most-recent. Canvas state changes will show more precise line-by-line
+ * diffs in greater detail.
+ */
 @Component({
   selector: 'tab-history',
   templateUrl: './tab-history.component.html',
@@ -63,6 +69,11 @@ export class TabHistoryComponent implements OnInit {
     });
   }
 
+  /**
+   * Switches the tab view to a colored diff between the currently selected
+   * state event and the previous state event.
+   * @param index Current index in the sortedHistory array, which is chronological
+   */
   openDiff(index: number): void {
     // Add listener for diff
     const entryCurrent = this.sortedHistory[index];
@@ -104,6 +115,9 @@ export class TabHistoryComponent implements OnInit {
     this.showList = false;
   }
 
+  /**
+   * Exits the diff view and returns the view to the full list of events.
+   */
   exitDiff() {
     this.showList = true;
   }

src/app/tab-preferences/tab-preferences.component.ts

@@ -19,6 +19,11 @@ import {MatSlideToggleChange} from '@angular/material/slide-toggle';
 import {ChromeBridgeService} from '../chrome-bridge.service';
 import {PreferencesService} from '../preferences.service';
 
+/**
+ * The Preferences tab displays available session-level capablities. It also
+ * presents a number of extension settings to provide more developer control
+ * over the debugging.
+ */
 @Component({
   selector: 'tab-preferences',
   templateUrl: './tab-preferences.component.html',
@@ -46,20 +51,34 @@ export class TabPreferencesComponent implements OnInit {
       await this.preferences.getFlagDebugExtension();
   }
 
+  /**
+   * Click handler to show header on the webpage.
+   */
   showHeader() {
     this.chromeBridge.injectHeaderDom();
   }
 
+  /**
+   * Click handler to prompt the user for the project SDK folder.
+   */
   loadSdk() {
     this.chromeBridge.loadSdk();
   }
 
+  /**
+   * Click handler when the Debug Client toggle is changed.
+   * @param event Toggle event
+   */
   async onChangeDebugClient(event: MatSlideToggleChange) {
     const {checked} = event;
     this.preferencesDebugClient = checked;
     await this.preferences.setFlagDebugClient(checked);
   }
 
+  /**
+   * Click handler when the Debug Extension toggle is changed.
+   * @param event Toggle event
+   */
   async onChangeDebugExtension(event: MatSlideToggleChange) {
     const {checked} = event;
     this.preferencesDebugExtension = checked;

src/app/tab-ttsmark/tab-ttsmark.component.ts

@@ -17,6 +17,10 @@
 import {Component, OnInit} from '@angular/core';
 import {ChromeBridgeService} from '../chrome-bridge.service';
 
+/**
+ * The TTS Mark tab allows one to send a custom TTS mark to the client.
+ * Suggestion chips appear below the input prompt to fill in the prompt.
+ */
 @Component({
   selector: 'tab-ttsmark',
   templateUrl: './tab-ttsmark.component.html',
@@ -37,10 +41,18 @@ export class TabTtsmarkComponent implements OnInit {
     });
   }
 
+  /**
+   * Click handler for suggestion chips, which will update the value of
+   * the input field.
+   * @param mark TTS Mark being selected
+   */
   prepopulate(mark: string) {
     this.markInput = mark;
   }
 
+  /**
+   * Sends a TTS Mark to the client.
+   */
   run() {
     this.chromeBridge.sendOnTtsMark(this.markInput || '');
   }

src/app/tab-update/tab-update.component.ts

@@ -18,6 +18,10 @@ import {Component, OnInit} from '@angular/core';
 import jsonRepair from '../../utils/json-repair';
 import {ChromeBridgeService} from '../chrome-bridge.service';
 
+/**
+ * The Update tab allows one to send JSON data to the client. Suggestion
+ * chips appear below the input prompt to fill in the prompt.
+ */
 @Component({
   selector: 'tab-update',
   templateUrl: './tab-update.component.html',
@@ -38,10 +42,18 @@ export class TabUpdateComponent implements OnInit {
     });
   }
 
+  /**
+   * Click handler for suggestion chips, which will update the value of
+   * the input field.
+   * @param payload Stringified JSON being selected
+   */
   prepopulate(payload: string) {
     this.updateInput = payload;
   }
 
+  /**
+   * Sends a properly formatted JSON string to the client.
+   */
   run() {
     const json = jsonRepair(this.updateInput || '{}');
     this.chromeBridge.sendOnUpdate(json);

src/content-script.ts

@@ -14,6 +14,12 @@
  * limitations under the License.
  */
 
+/**
+ * @fileoverview Event listeners that commuciate with the page without
+ * interfering with normal page operations.
+ * This runs in a sandbox, with restricted access to novel Window objects.
+ */
+
 import {InteractiveCanvasWindow} from './types';
 
 declare let window: InteractiveCanvasWindow;
@@ -31,9 +37,6 @@ scriptsToLoad.forEach(script => {
   };
 });
 
-// Event listeners that commuciate with the page without interfering with
-// normal page operations.
-// This runs in a sandbox, with restricted access to novel Window objects.
 document.addEventListener('InteractiveCanvas_Init', (e: Event) => {
   const event = e as MessageEvent;
   window.interactiveCanvasExists = event.data;

src/interactive-canvas.ts

@@ -14,6 +14,10 @@
  * limitations under the License.
  */
 
+/**
+ * Types for Interactive Canvas.
+ * @see https://developers.google.com/assistant/interactivecanvas/reference
+ */
 export interface InteractiveCanvas {
   ready: (callbacks: InteractiveCanvasCallbacks) => void;
   sendTextQuery: (textQuery: string) => Promise<State>;
@@ -24,6 +28,10 @@ export interface InteractiveCanvas {
   };
 }
 
+/**
+ * Types for Interactive Canvas callbacks.
+ * @see https://developers.google.com/assistant/interactivecanvas/reference#interactivecanvascallbacks
+ */
 interface InteractiveCanvasCallbacks {
   onUpdate: (data: Object[]) => Promise<void> | undefined;
   onTtsMark: (markName: string) => void;

src/types.ts

@@ -25,23 +25,35 @@ export interface CanvasHistory {
   label: string;
 }
 
+/**
+ * @see https://wicg.github.io/file-system-access/#api-filesystemdirectoryhandle-getdirectoryhandle
+ */
 export interface DirectoryHandler {
   entries: () => FileIterator;
   getDirectoryHandle: (path: string) => Promise<DirectoryHandler>;
   getFileHandle: (path: string) => Promise<FileHandler>;
 }
 
+/**
+ * @see https://wicg.github.io/file-system-access/#api-filesystemdirectoryhandle-asynciterable
+ */
 export interface FileIterator {
   next: () => {
     done: boolean;
     value?: [string, FileHandler];
   };
 }
 
+/**
+ * @see https://wicg.github.io/file-system-access/#api-filesystemdirectoryhandle-getfilehandle
+ */
 export interface FileHandler {
   getFile: () => Promise<File>;
 }
 
+/**
+ * @see https://wicg.github.io/file-system-access/#api-filesystemfilehandle-getfile
+ */
 export interface File {
   slice: () => Promise<Blob>;
   text: () => Promise<string>;
@@ -69,16 +81,18 @@ export interface InteractiveCanvasWindow extends Window {
     title: string;
     projectId: string;
     /**
-     * base64 representation of the project's logo
+     * base64 representation of the project's logo.
      */
     logoSrcData: string;
   };
   /**
-   * JSYaml is a 3P library that converts YAML to JSON
+   * JSYaml is a 3P library that converts YAML to JSON.
+   * @see https://www.npmjs.com/package/js-yaml
    */
   jsyaml: JSYaml;
   /**
-   * A browser operation that opens a file directory selector
+   * A browser operation that opens a file directory selector.
+   * @see https://web.dev/file-system-access/
    */
   showDirectoryPicker: () => Promise<DirectoryHandler>;
 }

src/webpage-script.ts

@@ -14,6 +14,11 @@
  * limitations under the License.
  */
 
+/**
+ * @fileoverview Code that runs in the context of the real page, without sandboxing.
+ * @see https://stackoverflow.com/questions/9602022/chrome-extension-retrieving-global-variable-from-webpage#answer-9636008
+ */
+
 import {
   CanvasHistory,
   DirectoryHandler,
@@ -24,6 +29,9 @@ import {
 
 declare let window: InteractiveCanvasWindow;
 
+/**
+ * Callback used when iterating through an SDK directory.
+ */
 type DirectoryIteratorCallback = (
   filename: string,
   handler: FileHandler
@@ -402,8 +410,6 @@ async function getImgData(blob: Blob): Promise<string> {
   });
 }
 
-// https://stackoverflow.com/questions/9602022/chrome-extension-retrieving-global-variable-from-webpage#answer-9636008
-// Code that runs in the context of the real page, without sandboxing.
 window.requestAnimationFrame(() => {
   const hasInteractiveCanvas = window.interactiveCanvas !== undefined;