Fix eclipsesource#567: Add JsDoc

Author: edgarmueller

src/core.ts

@@ -5,15 +5,43 @@ import {DataService} from './core/data.service';
 import {RendererService} from './core/renderer.service';
 import {StylingRegistry, StylingRegistryImpl} from './core/styling.registry';
 
+/**
+ * Represents a JSONForms service.
+ */
 export interface JsonFormService {
+
+  /**
+   * Disposes this service.
+   */
   dispose(): void;
 }
+
+/**
+ * Encapsulates instantiation logic of a JSONForms service.
+ */
 export interface JsonFormsServiceConstructable {
+  /**
+   * Constructor logic.
+   *
+   * @param {DataService} dataService the data service
+   * @param {JsonSchema} dataSchema the JSON schema describing the data
+   * @param {UISchemaElement} uiSchema the UI schema to be rendered
+   */
   new(dataService: DataService, dataSchema: JsonSchema, uiSchema: UISchemaElement): JsonFormService;
 }
+
+/**
+ * Annotation for registering a class as JSONForms service.
+ * @param config
+ * @constructor
+ */
 export const JsonFormsServiceElement = (config) => (cls: JsonFormsServiceConstructable) => {
   JsonFormsHolder.jsonFormsServices.push(cls);
 };
+
+/**
+ * Global JSONForms object that holds services and registries.
+ */
 export class JsonFormsHolder {
   public static rendererService = new RendererService();
   public static jsonFormsServices: Array<JsonFormsServiceConstructable> = [];

src/core/data.service.ts

@@ -1,14 +1,51 @@
 import {ControlElement} from '../models/uischema';
 import { getValuePropertyPair } from '../path.util';
 
+/**
+ * A listener that is notified whenever the underlying data changes.
+ */
 export interface DataChangeListener {
+
+  /**
+   * Determines whether this listener is interested in any data change.
+   * If this returns true, the notifyChange method of the listener will be called.
+   * @param {ControlElement} uischema the control element that is affected by the data change
+   * @returns whether this listener is interested in the given control element
+   */
   isRelevantKey(uischema: ControlElement): boolean;
+
+  /**
+   * Represents the listener's logic to be called in case of a data change that
+   * is relevant to the listener.
+   *
+   * @param {ControlElement} uischema the control element that is affected by the data change
+   * @param {any} newValue the changed data value
+   * @param {any} data the current data value
+   */
   notifyChange(uischema: ControlElement, newValue: any, data: any): void;
 }
+
+/**
+ * The data service that holds the data of a form and maintains
+ * a list of listeners that are notified whenever the data changes.
+ */
 export class DataService {
   private changeListeners: Array<DataChangeListener>= [];
+
+  /**
+   * Constructor
+   * .
+   * @param data the data object to be wrapped by the service
+   */
   constructor(private data: any) {
   }
+
+  /**
+   * Notifies any data change listeners about a data change.
+   *
+   * @param {ControlElement} uischema the affected control element
+   * @param newValue the new value of the data chunk
+   */
   notifyChange(uischema: ControlElement, newValue: any): void {
     if (uischema !== undefined && uischema !== null) {
       const pair = getValuePropertyPair(this.data, uischema.scope.$ref);
@@ -21,19 +58,40 @@ export class DataService {
       }
     });
   }
+
+  /**
+   * Register the given data change listener.
+   * @param {DataChangeListener} listener the listener to be registered
+   */
   registerChangeListener(listener: DataChangeListener): void {
     this.changeListeners.push(listener);
   }
+
+  /**
+   * Un-register the given data change listener.
+   * @param {DataChangeListener} listener the data change listener to be un-registered
+   */
   unregisterChangeListener(listener: DataChangeListener): void {
     this.changeListeners.splice(this.changeListeners.indexOf(listener), 1);
   }
+
+  /**
+   * Resolve the ref of the given control against the root data.
+   *
+   * @param {ControlElement} uischema
+   * @return {any} the de-referenced data chunk
+   */
   getValue(uischema: ControlElement): any {
     const pair = getValuePropertyPair(this.data, uischema.scope.$ref);
     if (pair.property === undefined) {
       return pair.instance;
     }
     return pair.instance[pair.property];
   }
+
+  /**
+   * Notifies all data change listeners initially.
+   */
   initialRootRun(): void {
     this.changeListeners.forEach(listener => {
       if (listener.isRelevantKey(null)) {

src/core/renderer.service.ts

@@ -5,17 +5,46 @@ import {DataService} from './data.service';
 import {Renderer} from './renderer';
 import {RankedTester} from './testers';
 
+/**
+ * The renderer service maintains a list of renderers and
+ * is responsible for finding the most applicable one given a UI schema, a schema
+ * and a data service.
+ */
 export class RendererService {
   private renderers: Array<{tester: RankedTester, renderer: string}> = [];
+
+  /**
+   * Register a renderer. A renderer is represented by the tag name of the corresponding
+   * HTML element, which is assumed to have been registered as a custom element.
+   *
+   * @param {RankedTester} tester a tester that determines whether when the renderer should be used
+   * @param {string} renderer the tag name of the HTML element that represents the renderer
+   */
   registerRenderer(tester: RankedTester, renderer: string): void {
     this.renderers.push({tester, renderer});
   }
+
+  /**
+   * Unregister a renderer.
+   * @param {RankedTester} tester the tester of the renderer to be un-registered.
+   *        Note that strict equality is used when un-registering renderers.
+   * @param {string} renderer the tag name of the HTML element that represents
+   *        the renderer to be un-registered
+   */
   unregisterRenderer(tester: RankedTester, renderer: string): void {
     this.renderers = _.filter(this.renderers, r =>
         // compare testers via strict equality
         r.tester !== tester || !_.eq(r.renderer, renderer)
     );
   }
+
+  /**
+   * Find the renderer that is capable of rendering the given UI schema.
+   * @param {UISchemaElement} uischema the UI schema to be rendered
+   * @param {JsonSchema} schema the JSON data schema the associated data schema
+   * @param {DataService} dataService the data service holding the data to be rendered
+   * @return {HTMLElement} the rendered HTML element
+   */
   getBestRenderer(uischema: UISchemaElement,
                   schema: JsonSchema,
                   dataService: DataService): HTMLElement {

src/core/renderer.ts

@@ -3,41 +3,91 @@ import { JsonSchema } from '../models/jsonSchema';
 import {DataService} from './data.service';
 import {Runtime, RUNTIME_TYPE, RuntimeListener} from './runtime';
 
+/**
+ * A renderer is a regular HTMLElement that has a render method which will
+ * manipulate the underlying document when called. It also provides several
+ * lifecycle hooks.
+ */
 export abstract class Renderer extends HTMLElement implements RuntimeListener {
+
+  /**
+   * The {@link UISchemaElement} to be rendered.
+   */
   protected uischema: UISchemaElement;
+
+  /**
+   * The {@link DataService} holding the data to be rendered.
+   */
   protected dataService: DataService;
+
+  /**
+   * The {@link JsonSchema} to be rendered.
+   */
   protected dataSchema: JsonSchema;
+
+  /**
+   * Set the UI schema.
+   * @param {UISchemaElement} uischema the UI schema element to be set
+   */
   setUiSchema(uischema: UISchemaElement) {
     this.uischema = uischema;
   }
 
+  /**
+   * Set the data service.
+   * @param {DataService} dataService the data service to be set
+   */
   setDataService(dataService: DataService) {
     this.dataService = dataService;
   }
 
+  /**
+   * Set the JSON data schema .
+   * @param {JsonSchema} dataSchema the data schema
+   */
   setDataSchema(dataSchema: JsonSchema) {
     this.dataSchema = dataSchema;
   }
 
+  /**
+   * Notify this renderer about any run-time changes.
+   *
+   * @param {RUNTIME_TYPE} type the type of runtime change
+   */
   notify(type: RUNTIME_TYPE): void {
-    //
+    // no-op
   }
 
+  /**
+   * Called when this renderer is inserted into a document.
+   */
   connectedCallback(): void {
     if (!this.uischema.hasOwnProperty('runtime')) {
-      const runtime = new Runtime();
-      this.uischema['runtime'] = runtime;
+      this.uischema['runtime'] = new Runtime();
     }
     const runtime = <Runtime>this.uischema['runtime'];
     runtime.addListener(this);
     this.render();
   }
+
+  /**
+   * Called when this renderer is removed from a document.
+   */
   disconnectedCallback(): void {
     this.dispose();
     const runtime = <Runtime>this.uischema['runtime'];
     runtime.removeListener(this);
   }
 
+  /**
+   * Represents the render logic, i.e. it manipulates the DOM in-place.
+   *
+   * @return {HTMLElement} the renderer HTML element
+   */
   abstract render(): HTMLElement;
+
+  /**
+   * Dispose this renderer.
+   */
   abstract dispose(): void;
 }

src/core/runtime.ts

@@ -1,42 +1,102 @@
+/**
+ * The different types of runtime related changes.
+ */
 export enum RUNTIME_TYPE {
   VALIDATION_ERROR, VISIBLE, ENABLED
 }
+
+/**
+ * A listener that is notified about any runtime related changes.
+ */
 export interface RuntimeListener {
+
+  /**
+   * Called when a runtime related property changes.
+   * @param {RUNTIME_TYPE} type the type of runtime change
+   */
   notify(type: RUNTIME_TYPE): void;
 }
+
+/**
+ * A runtime object holds information about runtime related properties
+ * of a rendered UI schema element, like the visible/disabled state and
+ * possible validation errors.
+ */
 export class Runtime {
   private _validationErrors: Array<string>;
   private _visible = true;
   private _enabled = true;
   private _listeners: Array<RuntimeListener> = [];
 
+  /**
+   * Whether the element is visible.
+   * @return {boolean} true, if the element is visible, false otherwise
+   */
   get visible(): boolean {return this._visible; };
+
+  /**
+   * Whether the element is enabled.
+   * @return {boolean} true, if the element is enabled, false otherwise
+   */
   get enabled(): boolean {return this._enabled; };
+
+  /**
+   * Returns the validation errors associated with the element.
+   * @return {Array<string>} the validation errors
+   */
   get validationErrors(): Array<string> {return this._validationErrors; };
 
+  /**
+   * Set the visibility state of the element
+   * @param {boolean} visible whether the element should be visible
+   */
   set visible(visible: boolean) {
     this._visible = visible;
     this.notifyListeners(RUNTIME_TYPE.VISIBLE);
   };
 
+  /**
+   * Set the enabled state of the element
+   * @param {boolean} enabled whether the element should be enabled
+   */
   set enabled(enabled: boolean) {
     this._enabled = enabled;
     this.notifyListeners(RUNTIME_TYPE.ENABLED);
   };
 
+  /**
+   * Set the validation errors.
+   *
+   * @param {string[]} validationErrors the validation errors
+   */
   set validationErrors(validationErrors: Array<string>) {
     this._validationErrors = validationErrors;
     this.notifyListeners(RUNTIME_TYPE.VALIDATION_ERROR);
   };
 
+  /**
+   * Add the given runtime listener.
+   *
+   * @param {RuntimeListener} listener the runtime listener to be added
+   */
   addListener(listener: RuntimeListener): void {
     this._listeners.push(listener);
   }
 
+  /**
+   * Remove the given runtime listener.
+   *
+   * @param {RuntimeListener} listener the runtime listener to be removed
+   */
   removeListener(listener: RuntimeListener): void {
     this._listeners.splice(this._listeners.indexOf(listener), 1);
   }
 
+  /**
+   * Notifies any runtime listeners about a runtime change.
+   *
+   * @param {RUNTIME_TYPE} type the runtime type
+   */
   private notifyListeners(type: RUNTIME_TYPE): void {
     this._listeners.forEach(listener => listener.notify(type));
   }