Add docstring

jtpio · Apr 2, 2020 · adf6a2f · adf6a2f
1 parent 3e3cf14
commit adf6a2f
Show file tree

Hide file tree

Showing 8 changed files with 189 additions and 38 deletions.
diff --git a/src/plugin.ts b/src/plugin.ts
@@ -17,6 +17,9 @@ import { MODULE_NAME, MODULE_VERSION } from './version';
 
 const EXTENSION_ID = 'ipylab:plugin';
 
+/**
+ * The default plugin.
+ */
 const extension: JupyterFrontEndPlugin<void> = {
   id: EXTENSION_ID,
   autoStart: true,
@@ -29,10 +32,10 @@ const extension: JupyterFrontEndPlugin<void> = {
     palette: ICommandPalette
   ): void => {
     // add globals
-    widgetExports.JupyterFrontEndModel._app = app;
-    widgetExports.ShellModel._shell = shell;
-    widgetExports.CommandRegistryModel._commands = app.commands;
-    widgetExports.CommandPaletteModel._palette = palette;
+    widgetExports.JupyterFrontEndModel.app = app;
+    widgetExports.ShellModel.shell = shell;
+    widgetExports.CommandRegistryModel.commands = app.commands;
+    widgetExports.CommandPaletteModel.palette = palette;
 
     registry.registerWidget({
       name: MODULE_NAME,

diff --git a/src/widgets/commands.ts b/src/widgets/commands.ts
@@ -7,6 +7,8 @@ import { ISerializers, WidgetModel } from '@jupyter-widgets/base';
 
 import { CommandRegistry } from '@lumino/commands';
 
+import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
+
 import { IDisposable } from '@lumino/disposable';
 
 import { MODULE_NAME, MODULE_VERSION } from '../version';
@@ -15,6 +17,9 @@ import { MODULE_NAME, MODULE_VERSION } from '../version';
  * The model for a command registry.
  */
 export class CommandRegistryModel extends WidgetModel {
+  /**
+   * The default attributes.
+   */
   defaults(): any {
     return {
       ...super.defaults(),
@@ -24,8 +29,14 @@ export class CommandRegistryModel extends WidgetModel {
     };
   }
 
+  /**
+   * Initialize a CommandRegistryModel instance.
+   *
+   * @param attributes The base attributes.
+   * @param options The initialization options.
+   */
   initialize(attributes: any, options: any): void {
-    this.commands = CommandRegistryModel._commands;
+    this._commands = CommandRegistryModel.commands;
     super.initialize(attributes, options);
     this.on('msg:custom', this._onMessage.bind(this));
     this.on('comm_live_update', () => {
@@ -38,6 +49,11 @@ export class CommandRegistryModel extends WidgetModel {
     this._sendCommandList();
   }
 
+  /**
+   * Handle a custom message from the backend.
+   *
+   * @param msg The message to handle.
+   */
   private _onMessage(msg: any): void {
     switch (msg.func) {
       case 'execute':
@@ -54,24 +70,42 @@ export class CommandRegistryModel extends WidgetModel {
     }
   }
 
+  /**
+   * Send the list of commands to the backend.
+   */
   private _sendCommandList(): void {
-    this.commands.notifyCommandChanged();
-    this.set('_commands', this.commands.listCommands());
+    this._commands.notifyCommandChanged();
+    this.set('_commands', this._commands.listCommands());
     this.save_changes();
   }
 
-  private _execute(payload: any): void {
-    const { id, args } = payload;
-    void this.commands.execute(id, args);
+  /**
+   * Execute a command
+   *
+   * @param bundle The command bundle.
+   */
+  private _execute(bundle: {
+    id: string;
+    args: ReadonlyPartialJSONObject;
+  }): void {
+    const { id, args } = bundle;
+    void this._commands.execute(id, args);
   }
 
-  private async _addCommand(payload: any): Promise<void> {
-    const { id, caption, label, iconClass } = payload;
-    if (this.commands.hasCommand(id)) {
+  /**
+   * Add a new command to the command registry.
+   *
+   * @param options The command options.
+   */
+  private async _addCommand(
+    options: CommandRegistry.ICommandOptions & { id: string }
+  ): Promise<void> {
+    const { id, caption, label, iconClass } = options;
+    if (this._commands.hasCommand(id)) {
       // TODO: handle this?
       return;
     }
-    const command = this.commands.addCommand(id, {
+    const command = this._commands.addCommand(id, {
       caption,
       label,
       iconClass,
@@ -87,8 +121,13 @@ export class CommandRegistryModel extends WidgetModel {
     this._sendCommandList();
   }
 
-  private _removeCommand(payload: any): void {
-    const { id } = payload;
+  /**
+   * Remove a command from the command registry.
+   *
+   * @param bundle The command bundle.
+   */
+  private _removeCommand(bundle: { id: string }): void {
+    const { id } = bundle;
     if (this._customCommands.has(id)) {
       this._customCommands.get(id).dispose();
     }
@@ -106,7 +145,8 @@ export class CommandRegistryModel extends WidgetModel {
   static view_module: string = null;
   static view_module_version = MODULE_VERSION;
 
-  private commands: CommandRegistry;
-  static _commands: CommandRegistry;
+  private _commands: CommandRegistry;
   private _customCommands = new ObservableMap<IDisposable>();
+
+  static commands: CommandRegistry;
 }
diff --git a/src/widgets/frontend.ts b/src/widgets/frontend.ts
@@ -11,7 +11,13 @@ import {
 
 import { MODULE_NAME, MODULE_VERSION } from '../version';
 
+/**
+ * The model for a JupyterFrontEnd.
+ */
 export class JupyterFrontEndModel extends WidgetModel {
+  /**
+   * The default attributes.
+   */
   defaults(): any {
     return {
       ...super.defaults(),
@@ -21,11 +27,17 @@ export class JupyterFrontEndModel extends WidgetModel {
     };
   }
 
+  /**
+   * Initialize a JupyterFrontEndModel instance.
+   *
+   * @param attributes The base attributes.
+   * @param options The initialization options.
+   */
   initialize(attributes: any, options: any): void {
-    this.app = JupyterFrontEndModel._app;
+    this._app = JupyterFrontEndModel.app;
     super.initialize(attributes, options);
     this.send({ event: 'lab_ready' }, {});
-    this.set('version', this.app.version);
+    this.set('version', this._app.version);
     this.save_changes();
   }
 
@@ -40,6 +52,6 @@ export class JupyterFrontEndModel extends WidgetModel {
   static view_module: string = null;
   static view_module_version = MODULE_VERSION;
 
-  private app: JupyterFrontEnd;
-  static _app: JupyterFrontEnd;
+  private _app: JupyterFrontEnd;
+  static app: JupyterFrontEnd;
 }
diff --git a/src/widgets/palette.ts b/src/widgets/palette.ts
@@ -8,9 +8,15 @@ import {
 } from '@jupyter-widgets/base';
 
 import { MODULE_NAME, MODULE_VERSION } from '../version';
-import { ICommandPalette } from '@jupyterlab/apputils';
+import { ICommandPalette, IPaletteItem } from '@jupyterlab/apputils';
 
+/**
+ * The model for a command palette.
+ */
 export class CommandPaletteModel extends WidgetModel {
+  /**
+   * The default attributes.
+   */
   defaults(): any {
     return {
       ...super.defaults(),
@@ -20,13 +26,24 @@ export class CommandPaletteModel extends WidgetModel {
     };
   }
 
+  /**
+   * Initialize a CommandPaletteModel instance.
+   *
+   * @param attributes The base attributes.
+   * @param options The initialization options.
+   */
   initialize(attributes: any, options: any): void {
-    this.palette = CommandPaletteModel._palette;
+    this._palette = CommandPaletteModel.palette;
     super.initialize(attributes, options);
 
     this.on('msg:custom', this._onMessage.bind(this));
   }
 
+  /**
+   * Handle a custom message from the backend.
+   *
+   * @param msg The message to handle.
+   */
   private _onMessage(msg: any): void {
     switch (msg.func) {
       case 'addItem':
@@ -37,13 +54,18 @@ export class CommandPaletteModel extends WidgetModel {
     }
   }
 
-  private _addItem(payload: any): void {
-    if (!this.palette) {
+  /**
+   * Add a new item to the command palette.
+   *
+   * @param options The item options.
+   */
+  private _addItem(options: IPaletteItem & { id: string }): void {
+    if (!this._palette) {
       // no-op if no palette
       return;
     }
-    const { id, category, args, rank } = payload;
-    void this.palette.addItem({ command: id, category, args, rank });
+    const { id, category, args, rank } = options;
+    void this._palette.addItem({ command: id, category, args, rank });
   }
 
   static serializers: ISerializers = {
@@ -57,6 +79,7 @@ export class CommandPaletteModel extends WidgetModel {
   static view_module: string = null;
   static view_module_version = MODULE_VERSION;
 
-  private palette: ICommandPalette;
-  static _palette: ICommandPalette;
+  private _palette: ICommandPalette;
+
+  static palette: ICommandPalette;
 }
diff --git a/src/widgets/panel.ts b/src/widgets/panel.ts
@@ -5,7 +5,13 @@ import { VBoxModel } from '@jupyter-widgets/controls';
 
 import { MODULE_NAME, MODULE_VERSION } from '../version';
 
+/**
+ * The model for a panel.
+ */
 export class PanelModel extends VBoxModel {
+  /**
+   * The default attributes.
+   */
   defaults(): any {
     return {
       ...super.defaults(),

diff --git a/src/widgets/shell.ts b/src/widgets/shell.ts
@@ -11,7 +11,13 @@ import {
 
 import { MODULE_NAME, MODULE_VERSION } from '../version';
 
+/**
+ * The model for a shell.
+ */
 export class ShellModel extends WidgetModel {
+  /**
+   * The default attributes.
+   */
   defaults(): any {
     return {
       ...super.defaults(),
@@ -21,12 +27,23 @@ export class ShellModel extends WidgetModel {
     };
   }
 
+  /**
+   * Initialize a ShellModel instance.
+   *
+   * @param attributes The base attributes.
+   * @param options The initialization options.
+   */
   initialize(attributes: any, options: any): void {
-    this.shell = ShellModel._shell;
+    this._shell = ShellModel.shell;
     super.initialize(attributes, options);
     this.on('msg:custom', this.onMessage.bind(this));
   }
 
+  /**
+   * Handle a custom message from the backend.
+   *
+   * @param msg The message to handle.
+   */
   private async onMessage(msg: any): Promise<void> {
     switch (msg.func) {
       case 'add': {
@@ -60,9 +77,9 @@ export class ShellModel extends WidgetModel {
         if (area === 'left' || area === 'right') {
           let handler;
           if (area === 'left') {
-            handler = this.shell['_leftHandler'];
+            handler = this._shell['_leftHandler'];
           } else {
-            handler = this.shell['_rightHandler'];
+            handler = this._shell['_rightHandler'];
           }
 
           // handle tab closed event
@@ -72,15 +89,15 @@ export class ShellModel extends WidgetModel {
 
           pWidget.addClass('jp-SideAreaWidget');
         }
-        this.shell.add(pWidget, area, args);
+        this._shell.add(pWidget, area, args);
         break;
       }
       case 'expandLeft': {
-        this.shell.expandLeft();
+        this._shell.expandLeft();
         break;
       }
       case 'expandRight': {
-        this.shell.expandRight();
+        this._shell.expandRight();
         break;
       }
       default:
@@ -99,6 +116,7 @@ export class ShellModel extends WidgetModel {
   static view_module: string = null;
   static view_module_version = MODULE_VERSION;
 
-  private shell: ILabShell;
-  static _shell: ILabShell;
+  private _shell: ILabShell;
+
+  static shell: ILabShell;
 }