Update the 'outline-view' documentation

- updates the documentation for the `outline-view`.
- in order to globally update the documentation for all `tree-widgets`,
including the `outline-view-widget`, the `tree-widget.tsx` documentation
was updated from `@theia/core`.

Signed-off-by: Vincent Fugnitto <vincent.fugnitto@ericsson.com>

packages/core/src/browser/widget-manager.ts

@@ -25,35 +25,45 @@ export const WidgetFactory = Symbol('WidgetFactory');
  */
 export interface WidgetFactory {
 
-    /*
-     * the factory's id
+    /**
+     * The factory id.
      */
     readonly id: string;
 
     /**
-     * Creates a widget and attaches it to the shell
-     * The options need to be serializable JSON data.
+     * Creates a widget and attaches it to the application shell.
+     * @param options serializable JSON data.
      */
     createWidget(options?: any): MaybePromise<Widget>;
 }
 
-/*
- * a serializable description to create a widget
+/**
+ * Representation of the `WidgetConstructionOptions`.
+ * Defines a serializable description to create widgets.
  */
 export interface WidgetConstructionOptions {
     /**
-     * the id of the widget factory to use.
+     * The id of the widget factory to use.
      */
     factoryId: string,
 
-    /*
-     * widget factory specific information
+    /**
+     * The widget factory specific information.
      */
     options?: any
 }
 
+/**
+ * Representation of a `didCreateWidgetEvent`.
+ */
 export interface DidCreateWidgetEvent {
+    /**
+     * The widget which was created.
+     */
     readonly widget: Widget;
+    /**
+     * The widget factory id.
+     */
     readonly factoryId: string;
 }
 
@@ -77,6 +87,12 @@ export class WidgetManager {
     protected readonly onDidCreateWidgetEmitter = new Emitter<DidCreateWidgetEvent>();
     readonly onDidCreateWidget: Event<DidCreateWidgetEvent> = this.onDidCreateWidgetEmitter.event;
 
+    /**
+     * Get the list of widgets created for the given factory id.
+     * @param factoryId the widget factory id.
+     *
+     * @returns the list of widgets created for the given factory id.
+     */
     getWidgets(factoryId: string): Widget[] {
         const result: Widget[] = [];
         for (const [key, widget] of this.widgets.entries()) {
@@ -87,6 +103,11 @@ export class WidgetManager {
         return result;
     }
 
+    /**
+     * Try and get the widget.
+     *
+     * @returns the widget if available, else `undefined`.
+     */
     tryGetWidget<T extends Widget>(factoryId: string, options?: any): T | undefined {
         const key = this.toKey({ factoryId, options });
         const existing = this.widgetPromises.get(key);
@@ -97,7 +118,9 @@ export class WidgetManager {
     }
 
     /**
-     * return the widget for the given description
+     * Get the widget for the given description.
+     *
+     * @returns a promise resolving to the widget if available, else `undefined.
      */
     async getWidget<T extends Widget>(factoryId: string, options?: any): Promise<T | undefined> {
         const key = this.toKey({ factoryId, options });
@@ -114,8 +137,8 @@ export class WidgetManager {
         return undefined;
     }
 
-    /*
-     * creates or returns the widget for the given description.
+    /**
+     * Creates or returns the widget for the given description.
      */
     async getOrCreateWidget<T extends Widget>(factoryId: string, options?: any): Promise<T> {
         const key = this.toKey({ factoryId, options });
@@ -146,8 +169,11 @@ export class WidgetManager {
         }
     }
 
-    /*
-     *  returns the construction description for the given widget, or undefined if the widget was not created through this manager.
+    /**
+     * Get the widget construction options.
+     * @param widget the widget.
+     *
+     * @returns the widget construction options if the widget was created through the manager, else `undefined`.
      */
     getDescription(widget: Widget): WidgetConstructionOptions | undefined {
         for (const [key, aWidget] of this.widgets.entries()) {
@@ -158,10 +184,22 @@ export class WidgetManager {
         return undefined;
     }
 
+    /**
+     * Convert the widget construction options to string.
+     * @param options the widget construction options.
+     *
+     * @returns the widget construction options represented as a string.
+     */
     protected toKey(options: WidgetConstructionOptions): string {
         return JSON.stringify(options);
     }
 
+    /**
+     * Convert the key into the widget construction options object.
+     * @param key the key.
+     *
+     * @returns the widget construction options object.
+     */
     protected fromKey(key: string): WidgetConstructionOptions {
         return JSON.parse(key);
     }

packages/core/src/browser/widgets/react-widget.tsx

@@ -41,5 +41,11 @@ export abstract class ReactWidget extends BaseWidget {
         ReactDOM.render(<React.Fragment>{this.render()}</React.Fragment>, this.node, () => this.onRender.dispose());
     }
 
+    /**
+     * Render the React widget in the DOM.
+     * - If the widget has been previously rendered,
+     * any subsequent calls will perform an update and only
+     * change the DOM if absolutely necessary.
+     */
     protected abstract render(): React.ReactNode;
 }

packages/outline-view/src/browser/outline-view-contribution.ts

@@ -25,7 +25,14 @@ import { CompositeTreeNode } from '@theia/core/lib/browser/tree';
 
 export const OUTLINE_WIDGET_FACTORY_ID = 'outline-view';
 
+/**
+ * Collection of `outline-view` commands.
+ */
 export namespace OutlineViewCommands {
+    /**
+     * Command which collapses all nodes
+     * from the `outline-view` tree.
+     */
     export const COLLAPSE_ALL: Command = {
         id: 'outlineView.collapse.all',
         iconClass: 'collapse-all'
@@ -81,6 +88,9 @@ export class OutlineViewContribution extends AbstractViewContribution<OutlineVie
         }
     }
 
+    /**
+     * Determine if the current widget is the `outline-view`.
+     */
     protected withWidget<T>(widget: Widget | undefined = this.tryGetWidget(), cb: (widget: OutlineViewWidget) => T): T | false {
         if (widget instanceof OutlineViewWidget && widget.id === OUTLINE_WIDGET_FACTORY_ID) {
             return cb(widget);

packages/outline-view/src/browser/outline-view-frontend-module.ts

@@ -49,6 +49,15 @@ export default new ContainerModule(bind => {
     bind(TabBarToolbarContribution).toService(OutlineViewContribution);
 });
 
+/**
+ * Create an `OutlineViewWidget`.
+ * - The creation of the `OutlineViewWidget` includes:
+ *  - The creation of the tree widget itself with it's own customized props.
+ *  - The binding of necessary components into the container.
+ * @param parent the Inversify container.
+ *
+ * @returns the `OutlineViewWidget`.
+ */
 function createOutlineViewWidget(parent: interfaces.Container): OutlineViewWidget {
     const child = createTreeContainer(parent);
 

packages/outline-view/src/browser/outline-view-service.ts

@@ -53,6 +53,11 @@ export class OutlineViewService implements WidgetFactory {
         return this.widget !== undefined && this.widget.isVisible;
     }
 
+    /**
+     * Publish the collection of outline view symbols.
+     * - Publishing includes setting the `OutlineViewWidget` tree with symbol information.
+     * @param roots the list of outline symbol information nodes.
+     */
     publish(roots: OutlineSymbolInformationNode[]): void {
         if (this.widget) {
             this.widget.setOutlineTree(roots);

packages/outline-view/src/browser/outline-view-tree.ts

@@ -22,8 +22,14 @@ export class OutlineViewTreeModel extends TreeModelImpl {
 
     @inject(TreeExpansionService) protected readonly expansionService: TreeExpansionService;
 
+    /**
+     * Handle the expansion of the tree node.
+     * - The method is a no-op in order to preserve focus on the editor
+     * after attempting to perform a `collapse-all`.
+     * @param node the expandable tree node.
+     */
     protected handleExpansion(node: Readonly<ExpandableTreeNode>): void {
-        // Do not select anything in order to preserve focus on the editor.
+        // no-op
     }
 
     async collapseAll(raw?: Readonly<CompositeTreeNode>): Promise<boolean> {

packages/outline-view/src/browser/outline-view-widget.tsx

@@ -31,11 +31,30 @@ import { Emitter } from '@theia/core';
 import { CompositeTreeNode } from '@theia/core/lib/browser';
 import * as React from 'react';
 
+/**
+ * Representation of an outline symbol information node.
+ */
 export interface OutlineSymbolInformationNode extends CompositeTreeNode, SelectableTreeNode, ExpandableTreeNode {
+    /**
+     * The `iconClass` for the given tree node.
+     */
     iconClass: string;
 }
 
+/**
+ * Collection of outline symbol information node functions.
+ */
 export namespace OutlineSymbolInformationNode {
+    /**
+     * Determine if the given tree node is an `OutlineSymbolInformationNode`.
+     * - The tree node is an `OutlineSymbolInformationNode` if:
+     *  - The node exists.
+     *  - The node is selectable.
+     *  - The node contains a defined `iconClass` property.
+     * @param node the tree node.
+     *
+     * @returns `true` if the given node is an `OutlineSymbolInformationNode`.
+     */
     export function is(node: TreeNode): node is OutlineSymbolInformationNode {
         return !!node && SelectableTreeNode.is(node) && 'iconClass' in node;
     }
@@ -64,8 +83,14 @@ export class OutlineViewWidget extends TreeWidget {
         this.addClass('theia-outline-view');
     }
 
+    /**
+     * Set the outline tree with the list of `OutlineSymbolInformationNode`.
+     * @param roots the list of `OutlineSymbolInformationNode`.
+     */
     public setOutlineTree(roots: OutlineSymbolInformationNode[]): void {
+        // Gather the list of available nodes.
         const nodes = this.reconcileTreeState(roots);
+        // Update the model root node, appending the outline symbol information nodes as children.
         this.model.root = {
             id: 'outline-view-root',
             name: 'Outline Root',
@@ -75,6 +100,12 @@ export class OutlineViewWidget extends TreeWidget {
         } as CompositeTreeNode;
     }
 
+    /**
+     * Reconcile the outline tree state, gathering all available nodes.
+     * @param nodes the list of `TreeNode`.
+     *
+     * @returns the list of tree nodes.
+     */
     protected reconcileTreeState(nodes: TreeNode[]): TreeNode[] {
         nodes.forEach(node => {
             if (OutlineSymbolInformationNode.is(node)) {
@@ -114,6 +145,14 @@ export class OutlineViewWidget extends TreeWidget {
         };
     }
 
+    /**
+     * Get the tooltip for the given tree node.
+     * - The tooltip is discovered when hovering over a tree node.
+     * - If available, the tooltip is the concatenation of the node name, and it's type.
+     * @param node the tree node.
+     *
+     * @returns the tooltip for the tree node if available, else `undefined`.
+     */
     protected getNodeTooltip(node: TreeNode): string | undefined {
         if (OutlineSymbolInformationNode.is(node)) {
             return node.name + ` (${node.iconClass})`;