docstrings 2

Author: cameron-toy

src/commands.ts

@@ -1,3 +1,6 @@
+/**
+ * A namespace for dashboard command ids.
+ */
 export namespace CommandIDs {
   export const deleteOutput = 'dashboard:delete-dashboard-widget';
   export const undo = 'dashboard:undo';

src/dashboard.tsx

@@ -22,7 +22,7 @@ import { Message } from '@lumino/messaging';
 
 import { IDragEvent } from '@lumino/dragdrop';
 
-import { DashboardLayout } from './custom_layout';
+import { DashboardLayout } from './layout';
 
 import { DashboardWidget } from './widget';
 

src/dbformat.ts

@@ -45,6 +45,9 @@ export interface IOutputInfo extends PartialJSONObject {
    */
   cellId: string;
 
+  /**
+   * The position and size of an output.
+   */
   pos: {
     top: number;
     left: number;

src/index.ts

@@ -51,7 +51,7 @@ import { CommandIDs } from './commands';
 
 import { ReadonlyJSONObject } from '@lumino/coreutils';
 
-import { DashboardLayout } from './custom_layout';
+import { DashboardLayout } from './layout';
 
 import { Widgetstore } from './widgetstore';
 

src/custom_layout.ts renamed to src/layout.ts

@@ -33,6 +33,9 @@ import { Dashboard } from './dashboard';
 
 import { getNotebookById } from './utils';
 
+/**
+ * The definition of a model object for a dashboard widget.
+ */
 export interface IDashboardModel extends DocumentRegistry.IModel {
   /**
    * The widget store for the dashboard.
@@ -49,24 +52,54 @@ export interface IDashboardModel extends DocumentRegistry.IModel {
    */
   readonly contentsManager: ContentsManager;
 
+  /**
+   * The metadata associated with the dashboard.
+   */
   metadata: IObservableJSON;
 
+  /**
+   * A signal emitted when the dashboard finishes deserializing from a file.
+   */
   loaded: Signal<this, void>;
 
+  /**
+   * The display mode of the dashboard.
+   */
   mode: Dashboard.Mode;
 
+  /**
+   * The path to the dashboard file.
+   */
   path: string;
 
+  /**
+   * The name of the dashboard.
+   */
   name: string;
 
+  /**
+   * The width of the dashboard in pixels.
+   */
   width: number;
 
+  /**
+   * The height of the dashboard in pixels.
+   */
   height: number;
 
+  /**
+   * The scroll mode of the dashboard.
+   */
   scrollMode: Dashboard.ScrollMode;
 }
 
+/**
+ * An implementation of a dashboard Model.
+ */
 export class DashboardModel extends DocumentModel implements IDashboardModel {
+  /**
+   * Construct a new dashboard model.
+   */
   constructor(options: DashboardModel.IOptions) {
     super(options.languagePreference, options.modelDB);
 
@@ -78,6 +111,9 @@ export class DashboardModel extends DocumentModel implements IDashboardModel {
     this.contentsManager = options.contentsManager || new ContentsManager();
   }
 
+  /**
+   * Deserialize the model from JSON.
+   */
   async fromJSON(value: IDashboardContent): Promise<void> {
     const outputs: Widgetstore.WidgetInfo[] = [];
 
@@ -122,6 +158,9 @@ export class DashboardModel extends DocumentModel implements IDashboardModel {
     // this.mode = 'present';
   }
 
+  /**
+   * Serialize the model to JSON.
+   */
   toJSON(): IDashboardContent {
     const notebookTracker = this.notebookTracker;
 
@@ -175,10 +214,16 @@ export class DashboardModel extends DocumentModel implements IDashboardModel {
     return file;
   }
 
+  /**
+   * Serialize the model to a string.
+   */
   toString(): string {
     return JSON.stringify(this.toJSON(), undefined, 2);
   }
 
+  /**
+   * Deserialize the model from a string.
+   */
   async fromString(value: string): Promise<void> {
     if (!value) {
       this._loaded.emit(void 0);

src/model.ts

@@ -26,20 +26,37 @@ import { Signal, ISignal } from '@lumino/signaling';
 import { DashboardIcons } from './icons';
 
 import { Widgetstore, WidgetPosition } from './widgetstore';
-import { DashboardLayout } from './custom_layout';
 
-// HTML element classes
+import { DashboardLayout } from './layout';
 
+/**
+ * The class name added to dashboard outputs
+ */
 const DASHBOARD_WIDGET_CLASS = 'pr-DashboardWidget';
 
+/**
+ * The class name for the widget drag mime.
+ */
 const DASHBOARD_WIDGET_MIME = 'pr-DashboardWidgetMine';
 
+/**
+ * The class name added to the children of dashboard outputs.
+ */
 const DASHBOARD_WIDGET_CHILD_CLASS = 'pr-DashboardWidgetChild';
 
+/**
+ * The class name added to editable dashboard outputs.
+ */
 const EDITABLE_WIDGET_CLASS = 'pr-EditableWidget';
 
+/**
+ * The class name added to dashboard outputs being dragged.
+ */
 const IN_DRAG_CLASS = 'pr-InDrag';
 
+/**
+ * The class name added to markdown dashboard outputs.
+ */
 const MARKDOWN_OUTPUT_CLASS = 'pr-MarkdownOutput';
 
 /**
@@ -237,7 +254,7 @@ export class DashboardWidget extends Widget {
   }
 
   /**
-   * Handle the `'dblclick'` event for the widget.
+   * Handle the `'dblclick'` event for the widget. Currently a no-op.
    */
   private _evtDblClick(event: MouseEvent): void {
     // Do nothing if it's not a left mouse press.
@@ -301,7 +318,7 @@ export class DashboardWidget extends Widget {
   }
 
   /**
-   * Handle `mousemove` event of widget
+   * Handle `mousemove` events for the widget.
    */
   private _evtMouseMove(event: MouseEvent): void {
     switch (this._mouseMode) {
@@ -316,6 +333,9 @@ export class DashboardWidget extends Widget {
     }
   }
 
+  /**
+   * Handle `mousemove` events when the widget mouseMode is `drag`.
+   */
   private _dragMouseMove(event: MouseEvent): void {
     const data = this._clickData;
     const { clientX, clientY } = event;
@@ -328,6 +348,9 @@ export class DashboardWidget extends Widget {
     }
   }
 
+  /**
+   * Handle `mousemove` events when the widget mouseMode is `resize`.
+   */
   private _resizeMouseMove(event: MouseEvent): void {
     const { pressX, pressY, pressWidth, pressHeight } = this._clickData;
 
@@ -358,6 +381,12 @@ export class DashboardWidget extends Widget {
     this.node.style.height = `${element.clientHeight + 2}px`;
   }
 
+  /**
+   * Determines whether the widget contains the point (left, top).
+   *
+   * ### Notes
+   * Both `left` and `top` are relative to the dashboard.
+   */
   containsPoint(left: number, top: number): boolean {
     const pos = {
       left,
@@ -369,6 +398,13 @@ export class DashboardWidget extends Widget {
     return overlap.type !== 'none';
   }
 
+  /**
+   * Determines whether the widget overlaps an area.
+   *
+   * @param _pos - the position and size of the test area.
+   *
+   * @returns - an object containing the type of overlap and this widget.
+   */
   overlaps(_pos: Widgetstore.WidgetPosition): DashboardWidget.Overlap {
     const { left, top, width, height } = _pos;
     const pos = this.pos;
@@ -430,6 +466,9 @@ export class DashboardWidget extends Widget {
     });
   }
 
+  /**
+   * Handle `mouseUp` events for the widget.
+   */
   private _evtMouseUp(event: MouseEvent): void {
     event.stopPropagation();
     event.preventDefault();
@@ -449,6 +488,10 @@ export class DashboardWidget extends Widget {
 
   /**
    * The widget's position on its dashboard.
+   *
+   * ### Notes
+   * When setting the widget pos, fields that you don't want to modify
+   * can be set as `undefined`.
    */
   get pos(): WidgetPosition {
     return {
@@ -565,13 +608,19 @@ export class DashboardWidget extends Widget {
     return this._ready;
   }
 
+  /**
+   * Whether the widget can be moved during a resize.
+   */
   get locked(): boolean {
     return this._locked;
   }
   set locked(newState: boolean) {
     this._locked = newState;
   }
 
+  /**
+   * The content of the widget.
+   */
   get content(): Widget {
     return this._content;
   }
@@ -641,17 +690,29 @@ export namespace DashboardWidget {
     fit?: boolean;
   }
 
+  /**
+   * A type for desccribing the direction of an overlap.
+   */
   export type Direction = 'left' | 'right' | 'up' | 'down' | 'none';
 
+  /**
+   * A type for describing an overlap between two widgets.
+   */
   export type Overlap = {
     widget: DashboardWidget;
     type: Direction;
   };
 
+  /**
+   * Create a unique widget id.
+   */
   export function createDashboardWidgetId(): string {
     return `DashboardWidget-${UUID.uuid4()}`;
   }
 
+  /**
+   * Create a resizer element for a dashboard widget.
+   */
   export function createResizer(): HTMLElement {
     const resizer = document.createElement('div');
     resizer.classList.add('pr-Resizer');
@@ -665,6 +726,18 @@ export namespace DashboardWidget {
     return resizer;
   }
 
+  /**
+   * Create a dashboard widget based on a WidgetInfo object.
+   *
+   * @param options - the options used to create the widget.
+   *
+   * @param notebookTracker - a notebook tracker used to locate a
+   * notebook/cell for the widget given a notebook/cell id.
+   *
+   * @param fit - whether to fit the new widget to its content.
+   *
+   * @returns - a new dashboard widget.
+   */
   export function createWidget(
     options: Widgetstore.WidgetInfo,
     notebookTracker: INotebookTracker,
@@ -701,6 +774,10 @@ export namespace DashboardWidget {
     return widget;
   }
 
+  /**
+   * A type to describe the different kinds of mouseMoves that can occur
+   * on a widget.
+   */
   export type MouseMode = 'drag' | 'resize' | 'none';
 
   /**
@@ -740,8 +817,11 @@ namespace Private {
    * mouse is moved beyond a certain distance (DRAG_THRESHOLD).
    *
    * @param prevX - X Coordinate of the mouse pointer during the mousedown event
+   *
    * @param prevY - Y Coordinate of the mouse pointer during the mousedown event
+   *
    * @param nextX - Current X Coordinate of the mouse pointer
+   *
    * @param nextY - Current Y Coordinate of the mouse pointer
    */
   export function shouldStartDrag(

src/widget.ts

@@ -10,7 +10,7 @@ import { Cell } from '@jupyterlab/cells';
 
 import { getNotebookById, getCellById } from './utils';
 
-import { IDashboardChange, DashboardLayout } from './custom_layout';
+import { IDashboardChange, DashboardLayout } from './layout';
 
 import { Dashboard } from './dashboard';