Added documentation for Label Provider and Contribution

packages/core/src/browser/label-provider.ts

@@ -47,10 +47,19 @@ export const FOLDER_ICON = DEFAULT_FOLDER_ICON;
 export const FILE_ICON = DEFAULT_FILE_ICON;
 
 export const LabelProviderContribution = Symbol('LabelProviderContribution');
+/**
+ * A {@link LabelProviderContribution} determines how specific elements/nodes are displayed in the workbench.
+ * Theia views use a common {@link LabelProvider} to determine the label and/or an icon for elements shown in the UI. This includes elements in lists
+ * and trees, but also view specific locations like headers. The common {@link LabelProvider} collects all {@links LabelProviderContribution} and delegates
+ * to the contribution with the highest priority. This is determined via calling the {@link LabelProviderContribution.canHandle} function, so contributions
+ * define which elements they are responsible for.
+ * As arbitrary views can consume LabelProviderContributions, they must be generic for the covered element type, not view specific. Label providers and
+ * contributions can be used for arbitrary element and node types, e.g. for markers or domain-specific elements.
+ */
 export interface LabelProviderContribution {
 
     /**
-     * whether this contribution can handle the given element and with what priority.
+     * Determines whether this contribution can handle the given element and with what priority.
      * All contributions are ordered by the returned number if greater than zero. The highest number wins.
      * If two or more contributions return the same positive number one of those will be used. It is undefined which one.
      */
@@ -78,7 +87,7 @@ export interface LabelProviderContribution {
     readonly onDidChange?: Event<DidChangeLabelEvent>;
 
     /**
-     * Check whether the given element is affected by the given change event.
+     * Checks whether the given element is affected by the given change event.
      * Contributions delegating to the label provider can use this hook
      * to perform a recursive check.
      */
@@ -256,6 +265,16 @@ export class DefaultUriLabelProviderContribution implements LabelProviderContrib
     }
 }
 
+/**
+ * The {@link LabelProvider} determines how elements/nodes are displayed in the workbench. For any element, it can determine a short label, a long label
+ * and an icon. The {@link LabelProvider} is to be used in lists, trees and tables, but also view specific locations like headers.
+ * The common {@link LabelProvider} can be extended/adapted via {@link LabelProviderContribution}s. For every element, the {@links LabelProvider} will determine the
+ * {@link LabelProviderContribution} with the hightest priority and delegate to it. Theia registers default {@link LabelProviderContribution} for common types, e.g.
+ * the {@link DefaultUriLabelProviderContribution} for elements that have a URI.
+ * Using the {@link LabelProvider} across the workbench ensures a common look and feel for elements across multiple views. To adapt the way how specific
+ * elements/nodes are rendered, use a {@link LabelProviderContribution} rather than adapting or sub classing the {@link LabelProvider}. This way, your adaptation
+ * is applied to all views in Theia that use the {@link LabelProvider}
+ */
 @injectable()
 export class LabelProvider implements FrontendApplicationContribution {
 
@@ -314,6 +333,10 @@ export class LabelProvider implements FrontendApplicationContribution {
         return this.getIcon(URIIconReference.create('folder'));
     }
 
+    /**
+     * Get the icon class from the list of available {@link LabelProviderContribution} for the given element.
+     * @return the icon class
+     */
     getIcon(element: object): string {
         const contributions = this.findContribution(element);
         for (const contribution of contributions) {
@@ -326,6 +349,10 @@ export class LabelProvider implements FrontendApplicationContribution {
         return '';
     }
 
+    /**
+     * Get a short name from the list of available {@link LabelProviderContribution} for the given element.
+     * @return the short name
+     */
     getName(element: object): string {
         const contributions = this.findContribution(element);
         for (const contribution of contributions) {
@@ -338,6 +365,10 @@ export class LabelProvider implements FrontendApplicationContribution {
         return '<unknown>';
     }
 
+    /**
+     * Get a long name from the list of available {@link LabelProviderContribution} for the given element.
+     * @return the long name
+     */
     getLongName(element: object): string {
         const contributions = this.findContribution(element);
         for (const contribution of contributions) {