Add comments for documentation

Author: IsabelParedes

src/controls.ts

@@ -1,11 +1,17 @@
 import { GUI } from 'dat.gui';
+
 import { Color } from 'three';
+
 import { URDFJoint } from 'urdf-loader';
 
 interface IJoints {
   [name: string]: URDFJoint;
 }
 
+/**
+ * URDFControls: a GUI panel for controlling the viewer settings and 
+ * the robot joints
+ */
 export class URDFControls extends GUI {
   private _workspaceFolder: any;
   private _sceneFolder: any;
@@ -22,6 +28,9 @@ export class URDFControls extends GUI {
     joints: {}
   };
 
+  /**
+   * Creates a controls panel with the default folders
+   */
   constructor() {
     super({ autoPlace: false });
 
@@ -44,22 +53,43 @@ export class URDFControls extends GUI {
     this._jointsFolder.domElement.setAttribute('class', 'dg joints-folder');
   }
 
+  /**
+   * Retrieves the folder with workspace settings
+   */
   get workspaceFolder() {
     return this._workspaceFolder;
   }
 
+  /**
+   * Retrieves the folder with scene settings
+   */
   get sceneFolder() {
     return this._sceneFolder;
   }
 
+  /**
+   * Retrieves the folder with joints settings
+   */
   get jointsFolder() {
     return this._jointsFolder;
   }
 
+  /**
+   * Checks if a given object is empty {}
+   * 
+   * @param obj - The object to check
+   * @returns - True when the object is empty, or false when it is not empty
+   */
   private _isEmpty(obj: object): boolean {
     return Object.keys(obj).length === 0;
   }
 
+  /**
+   * Creates an input box and a button to modify the working path
+   * 
+   * @param workingPath - The path where the loader looks for mesh files
+   * @returns - The controls to trigger callbacks when the path is changed
+   */
   createWorkspaceControls(workingPath = '') {
     if (this._isEmpty(this.controls.path)) {
       this._workingPath = workingPath;
@@ -79,6 +109,13 @@ export class URDFControls extends GUI {
     return this.controls.path;
   }
 
+  /**
+   * Creates color selectors to modify the scene background and grid
+   * 
+   * @param bgColor - The background color as a three.js Color
+   * @param gridColor - The grid color as a three.js Color
+   * @returns - The controls to trigger callbacks when the colors are changed
+   */
   createSceneControls(
     bgColor = new Color(0x263238),
     gridColor = new Color(0x263238)
@@ -115,7 +152,13 @@ export class URDFControls extends GUI {
     return this.controls.scene;
   }
 
-  private _convertColor2Array(color: THREE.Color): number[] {
+  /**
+   * Converts a three.js Color to an RGB Array
+   * 
+   * @param color - The three.js Color to convert
+   * @returns - The [R, G, B] Array with range [0, 255]
+   */
+  private _convertColor2Array(color: Color): number[] {
     // Note: using hex value instead of the RGB values in Color because
     // those are dependant on the color space
     const hexColor = color.getHexString();
@@ -127,6 +170,12 @@ export class URDFControls extends GUI {
     return colorArray;
   }
 
+  /**
+   * Creates number sliders for each movable robot joint
+   * 
+   * @param joints - An object containing all of the robot's joints
+   * @returns - The controls to trigger callbacks when any joint value changes
+   */
   createJointControls(joints: IJoints) {
     if (this._isEmpty(this.controls.joints)) {
       Object.keys(joints).forEach((name: string) => {

src/factory.ts

@@ -7,7 +7,7 @@ import {
 import { URDFWidget, URDFPanel } from './widget';
 
 /**
- * A widget factory to create new instances of URDFWidgets
+ * URDFWidgetFactory: a widget factory to create new instances of URDFWidgets
  */
 export class URDFWidgetFactory extends ABCWidgetFactory<
   URDFWidget,
@@ -17,7 +17,9 @@ export class URDFWidgetFactory extends ABCWidgetFactory<
     super(options);
   }
 
-  // Create new URDFWidget given a context (file info)
+  /**
+   * Create new URDFWidget given a context (file info)
+   */
   protected createNewWidget(
     context: DocumentRegistry.IContext<DocumentModel>
   ): URDFWidget {

src/icons.ts

@@ -2,6 +2,9 @@ import { LabIcon } from '@jupyterlab/ui-components';
 
 import urdf_logo from '/style/icons/urdf_logo.svg';
 
+/**
+ * Creates an icon for the URDF extension from a custom SVG
+ */
 export const urdf_icon = new LabIcon({
   name: 'urdf:icon/logo',
   svgstr: urdf_logo

src/index.ts

@@ -32,7 +32,9 @@ import { IEditorLanguageRegistry } from '@jupyterlab/codemirror';
 // Name of the factory that creates the URDF widgets
 const FACTORY = 'URDF Widget Factory';
 
-// Export token so other extensions can require it
+/** 
+ * Export token so other extensions can require it
+ */
 export const IURDFTracker = new Token<IWidgetTracker<URDFWidget>>(
   'urdf-tracker'
 );

src/layout.ts

@@ -1,10 +1,15 @@
 import { Message } from '@lumino/messaging';
+
 import { PanelLayout, Widget } from '@lumino/widgets';
+
 import { DocumentRegistry, DocumentModel } from '@jupyterlab/docregistry';
 
 import { Vector2, Color } from 'three';
+
 import { URDFControls } from './controls';
+
 import { URDFRenderer } from './renderer';
+
 import { URDFLoadingManager } from './robot';
 
 interface IURDFColors {
@@ -13,7 +18,7 @@ interface IURDFColors {
 }
 
 /**
- * A URDF layout to host the URDF viewer
+ * URDFLayout: A layout panel to host the URDF viewer
  */
 export class URDFLayout extends PanelLayout {
   private _host: HTMLElement;
@@ -47,6 +52,7 @@ export class URDFLayout extends PanelLayout {
    */
   dispose(): void {
     this._renderer.dispose();
+    this._loader.dispose();
     super.dispose();
   }
 
@@ -76,11 +82,21 @@ export class URDFLayout extends PanelLayout {
     return;
   }
 
+  /**
+   * Updates the viewer with any new changes on the file
+   * 
+   * @param urdfString - The contents of the file with the new changes
+   */
   updateURDF(urdfString: string): void {
     this._loader.setRobot(urdfString);
     this._renderer.setRobot(this._loader.robotModel);
   }
 
+  /**
+   * Sets the robot model initially and configures loader with default values
+   * 
+   * @param context - Contains the URDF file and its parameters
+   */
   setURDF(context: DocumentRegistry.IContext<DocumentModel>): void {
     // Default to parent directory of URDF file
     const filePath = context.path;
@@ -100,13 +116,25 @@ export class URDFLayout extends PanelLayout {
     }
   }
 
+  /**
+   * Retrieves the values for any color variable declared in CSS
+   * 
+   * @param colorName - The variable name of the color. Ex: '--jp-layout-color1'
+   * @returns - The values of the color as a three.js Color
+   */
   private _getThemeColor(colorName: string): Color | void {
     const colorString = window
       .getComputedStyle(document.documentElement)
       .getPropertyValue(colorName);
     return this._parseColor(colorString);
   }
 
+  /**
+   * Converts keyword or hex color definitions into three.js Color
+   * 
+   * @param color - A color string such as: 'red', '#aaa', or '#232323'
+   * @returns - The same color transformed to a three.js Color
+   */
   private _parseColor(color: string): Color | void {
     let parsedColor;
     if (color[0] !== '#') {
@@ -230,6 +258,9 @@ export class URDFLayout extends PanelLayout {
     this._host.appendChild(this._controlsPanel.domElement);
   }
 
+  /**
+   * Sets the size of the rendered view to match the host window size
+   */
   private _resizeWorkspace(): void {
     const rect = this.parent?.node.getBoundingClientRect();
     this._host.style.height = rect?.height + 'px';

src/renderer.ts

@@ -1,5 +1,7 @@
 import * as THREE from 'three';
+
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
+
 import { URDFRobot } from 'urdf-loader';
 
 /**
@@ -12,6 +14,9 @@ import { URDFRobot } from 'urdf-loader';
  *   Z
  */
 
+/**
+ * URDFRenderer: a renderer to manage the view of a scene with a robot
+ */
 export class URDFRenderer extends THREE.WebGLRenderer {
   private _scene: THREE.Scene;
   private _camera: THREE.PerspectiveCamera;
@@ -20,6 +25,12 @@ export class URDFRenderer extends THREE.WebGLRenderer {
   private _colorGround = new THREE.Color();
   private _robotIndex = -1;
 
+  /**
+   * Creates a renderer to manage the scene elements
+   * 
+   * @param colorSky - The color of the scene background
+   * @param colorGround - The color of the ground (grid) 
+   */
   constructor(
     colorSky = new THREE.Color(0x263238),
     colorGround = new THREE.Color(0x263238)
@@ -45,11 +56,17 @@ export class URDFRenderer extends THREE.WebGLRenderer {
     this._initControls();
   }
 
+  /**
+   * Initializes the camera 
+   */
   private _initCamera(): void {
     this._camera.position.set(4, 4, 4);
     this._camera.lookAt(0, 0, 0);
   }
 
+  /**
+   * Initializes the orbital controls
+   */
   private _initControls(): void {
     this._controls.rotateSpeed = 2.0;
     this._controls.zoomSpeed = 5;
@@ -61,6 +78,9 @@ export class URDFRenderer extends THREE.WebGLRenderer {
     this._controls.addEventListener('change', () => this.redraw());
   }
 
+  /**
+   * Initializes the scene
+   */
   private _initScene(): void {
     this._scene.background = this._colorSky;
     this._scene.up = new THREE.Vector3(0, 0, 1); // Z is up
@@ -69,7 +89,11 @@ export class URDFRenderer extends THREE.WebGLRenderer {
     this._addLights();
   }
 
+  /**
+   * Adds a plane representing the ground to the scene
+   */
   private _addGround(): void {
+    // TODO: fix shadows
     const ground = new THREE.Mesh(
       new THREE.PlaneGeometry(40, 40),
       new THREE.ShadowMaterial({ opacity: 0.5 })
@@ -80,6 +104,9 @@ export class URDFRenderer extends THREE.WebGLRenderer {
     this._scene.add(ground);
   }
 
+  /**
+   * Adds a grid to the scene with ground color given to the constructor()
+   */
   private _addGrid(): void {
     const grid = new THREE.GridHelper(
       50,
@@ -91,6 +118,9 @@ export class URDFRenderer extends THREE.WebGLRenderer {
     this._scene.add(grid);
   }
 
+  /**
+   * Adds three lights to the scene
+   */
   private _addLights(): void {
     const directionalLight = new THREE.DirectionalLight(0xffffff, 2.0);
     directionalLight.castShadow = true;
@@ -116,6 +146,9 @@ export class URDFRenderer extends THREE.WebGLRenderer {
     this._scene.add(hemisphereLight);
   }
 
+  /**
+   * Updates the hemisphere light to reflect the sky and ground colors
+   */
   private _updateLights(): void {
     const hemisphereLight = new THREE.HemisphereLight(
       this._colorSky,
@@ -160,6 +193,11 @@ export class URDFRenderer extends THREE.WebGLRenderer {
     this.redraw();
   }
 
+  /**
+   * Changes the height of the grid in the vertical axis (y-axis for three.js)
+   * 
+   * @param height - The height to shift the grid to
+   */
   setGridHeight(height = 0): void {
     const gridIndex = this._scene.children
       .map(i => i.type)
@@ -168,6 +206,11 @@ export class URDFRenderer extends THREE.WebGLRenderer {
     this.redraw();
   }
 
+  /**
+   * Adds a robot to the scene or updates the existing robot
+   * 
+   * @param robot 
+   */
   setRobot(robot: URDFRobot): void {
     if (this._robotIndex < 0) {
       this._scene.add(robot);
@@ -180,6 +223,9 @@ export class URDFRenderer extends THREE.WebGLRenderer {
     this.redraw();
   }
 
+  /**
+   * Refreshes the viewer by re-rendering the scene and its elements
+   */
   redraw(): void {
     this.render(this._scene, this._camera);
   }