Documentation for TreeDecorator & TreeDecoratorService

Fixes #8696
- Refine documentation for `TreeDecorator`
- Refine documentation for `TreeDecoratorService`
Signed-off-by: Tobias Ortmayr <tortmayr@eclipsesource.com>

packages/core/src/browser/tree/tree-decorator.ts

@@ -20,7 +20,38 @@ import { Event, Emitter, Disposable, DisposableCollection, MaybePromise } from '
 import { WidgetDecoration } from '../widget-decoration';
 
 /**
- * Tree decorator that can change the look and the style of the tree items within a widget.
+ * The {@link TreeDecorator} allows adapting the look and the style of the tree items within a widget. Changes are reflected in
+ * the form of `decoration data`. This `decoration data` is a map storing {@link TreeDecoration.Data} for affected tree nodes (using the unique node id as key).
+ * It is important to notice that there is no common contribution point for `TreeDecorators`. Instead, each {@link TreeDecoratorService} is
+ * supposed to declare its own contribution provider for `TreeDecorators`.
+ *
+ * ### Example usage
+ * A simple tree decorator that changes the background color of each tree node to `red`.
+ *
+ * ```typescript
+ * @injectable()
+ * export class MyTreeDecorator implements TreeDecorator {
+ *     id = 'myTreeDecorator';
+ *
+ *     protected readonly emitter = new Emitter<(tree: Tree) => Map<string, TreeDecoration.Data>>();
+ *
+ *     get onDidChangeDecorations(): Event<(tree: Tree) => Map<string, TreeDecoration.Data>> {
+ *         return this.emitter.event;
+ *     }
+ *
+ *     decorations(tree: Tree): MaybePromise<Map<string, TreeDecoration.Data>> {
+ *         const result = new Map();
+ *
+ *         if (tree.root === undefined) {
+ *             return result;
+ *         }
+ *         for (const treeNode of new DepthFirstTreeIterator(tree.root)) {
+ *             result.set(treeNode.id,<TreeDecoration.Data>{backgroundColor:'red'})
+ *         }
+ *         return result;
+ *     }
+ * }
+ * ```
  */
 export interface TreeDecorator {
 
@@ -30,25 +61,40 @@ export interface TreeDecorator {
     readonly id: string;
 
     /**
-     * Fired when this decorator has calculated all the decoration data for the tree nodes. Keys are the unique identifier of the tree nodes.
+     * Fired when this decorator has calculated all the `decoration data` for the tree nodes.
      */
     readonly onDidChangeDecorations: Event<(tree: Tree) => Map<string, TreeDecoration.Data>>;
 
     /**
-     * Returns with the current decoration data for the tree argument.
+     * Computes the current `decoration data` for the given tree. Might return a promise if the computation is handled asynchronously.
      *
      * @param tree the tree to decorate.
+     *
+     * @returns (a promise of) a map containing the current {@linkTreeDecoration.Data} for each node. Keys are the unique identifier of the tree nodes.
      */
     decorations(tree: Tree): MaybePromise<Map<string, TreeDecoration.Data>>;
 
 }
 
+export const TreeDecoratorService = Symbol('TreeDecoratorService');
+
 /**
- * Decorator service which emits events from all known tree decorators.
- * Keys are the unique tree node IDs and the values
- * are the decoration data collected from all the decorators known by this service.
+ * The {@link TreeDecoratorService} manages a set of known {link TreeDecorator}s and emits events when
+ * any of the known decorators has changes. Typically, a `TreeDecoratorService` provides a contribution point that can be used to
+ * register {@link TreeDecorator}s exclusively for this service.
+ *
+ * ### Example usage
+ * ```typescript
+ * export const MyTreeDecorator = Symbol('MyTreeDecorator');
+ *
+ * @injectable()
+ * export class MyDecorationService extends AbstractTreeDecoratorService {
+ *     constructor(@inject(ContributionProvider) @named(MyTreeDecorator) protected readonly contributions: ContributionProvider<TreeDecorator>) {
+ *         super(contributions.getContributions());
+ *     }
+ * }
+ * ```
  */
-export const TreeDecoratorService = Symbol('TreeDecoratorService');
 export interface TreeDecoratorService extends Disposable {
 
     /**
@@ -57,18 +103,27 @@ export interface TreeDecoratorService extends Disposable {
     readonly onDidChangeDecorations: Event<void>;
 
     /**
-     * Returns with the decorators for the tree based on the actual state of this decorator service.
+     * Computes the decorations for the tree based on the actual state of this decorator service.
+     *
+     * @param tree the tree to decorate
+     *
+     * @returns (a promise of) the computed `decoration data`
      */
     getDecorations(tree: Tree): MaybePromise<Map<string, TreeDecoration.Data[]>>;
 
     /**
-     * Transforms the decorators argument into an object, so that it can be safely serialized into JSON.
+     * Transforms the `decoration data` into an object, so that it can be safely serialized into JSON.
+     * @param decorations the `decoration data` that should be deflated
+     *
+     * @returns the `decoration data` as serializable JSON object
      */
     deflateDecorators(decorations: Map<string, TreeDecoration.Data[]>): object;
 
     /**
      * Counterpart of the [deflateDecorators](#deflateDecorators) method. Restores the argument into a Map
-     * of tree node IDs and the corresponding decorations data array.
+     * of tree node IDs and the corresponding decorations data array (`decoration data`).
+     *
+     * @returns the deserialized `decoration data
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     inflateDecorators(state: any): Map<string, TreeDecoration.Data[]>;