#11021 Add API documentation for property-view and selection-service

packages/core/src/common/selection-service.ts

@@ -13,16 +13,22 @@
 //
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 // *****************************************************************************
+/* eslint-disable @typescript-eslint/no-explicit-any */
 
 import { injectable } from 'inversify';
 import { Emitter, Event } from '../common/event';
 
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
+/**
+ * `SelectionProvider` is implemented by services to notify listeners about selection changes.
+ */
 export interface SelectionProvider<T> {
     onSelectionChanged: Event<T | undefined>;
 }
 
+/**
+ * Singleton service that is used to share the current selection globally in a Theia application.
+ * On each change of selection, subscribers are notified and receive the updated selection object.
+ */
 @injectable()
 export class SelectionService implements SelectionProvider<Object | undefined> {
 

packages/property-view/src/browser/empty-property-view-widget-provider.tsx

@@ -20,6 +20,10 @@ import * as React from '@theia/core/shared/react';
 import { PropertyViewContentWidget } from './property-view-content-widget';
 import { DefaultPropertyViewWidgetProvider } from './property-view-widget-provider';
 
+/**
+ * Property view widget that is shown if no property data or selection is available.
+ * This widget is provided by the {@link EmptyPropertyViewWidgetProvider}.
+ */
 class EmptyPropertyViewWidget extends ReactWidget implements PropertyViewContentWidget {
 
     static readonly ID = 'theia-empty-property-view';
@@ -47,7 +51,7 @@ class EmptyPropertyViewWidget extends ReactWidget implements PropertyViewContent
 }
 
 /**
- * `DefaultPropertyViewWidgetProvider` is implemented to provide the PropertyViewEmptyWidget
+ * `EmptyPropertyViewWidgetProvider` is implemented to provide the {@link EmptyPropertyViewWidget}
  *  if the given selection is undefined or no other provider can handle the given selection.
  */
 @injectable()

packages/property-view/src/browser/property-data-service.ts

@@ -41,7 +41,7 @@ export interface PropertyDataService {
     /**
      * Provide property data for the given selection.
      * Resolve to a property view content widget.
-     * Never reject if `canHandle` return a positive number; otherwise should reject.
+     * Never reject if `canHandle` returns a positive number; otherwise should reject.
      */
     providePropertyData(selection: Object | undefined): Promise<Object | undefined>;
 

packages/property-view/src/browser/property-view-content-widget.ts

@@ -17,6 +17,11 @@
 import { Widget } from '@theia/core/lib/browser/widgets/widget';
 import { PropertyDataService } from './property-data-service';
 
+/**
+ * A widget that fetches the property data via the given {@link PropertyDataService} and the given selection
+ * and renders that property data.
+ * This widget can be provided by a registered `PropertyViewWidgetProvider`.
+ */
 export interface PropertyViewContentWidget extends Widget {
     updatePropertyViewContent(propertyDataService?: PropertyDataService, selection?: Object): void;
 }

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

@@ -40,7 +40,8 @@ export class PropertyViewService {
 
     /**
      * Return a property view widget provider with the highest priority for the given selection.
-     * Never reject, return DefaultProvider ('No properties available') if no other matches.
+     * Never reject, return the default provider ({@link EmptyPropertyViewWidgetProvider};
+     * displays `No properties available`) if there are no other matches.
      */
     async getProvider(selection: Object | undefined): Promise<PropertyViewWidgetProvider> {
         const provider = await this.prioritize(selection);

packages/property-view/src/browser/property-view-widget-provider.ts

@@ -20,6 +20,9 @@ import { PropertyDataService } from './property-data-service';
 import { PropertyViewContentWidget } from './property-view-content-widget';
 
 export const PropertyViewWidgetProvider = Symbol('PropertyViewWidgetProvider');
+/**
+ * The `PropertyViewWidgetProvider` should be implemented to provide a property view content widget for the given selection..
+ */
 export interface PropertyViewWidgetProvider {
     /**
      * A unique id for this provider.
@@ -58,8 +61,10 @@ export interface PropertyViewWidgetProvider {
     updateContentWidget(selection: Object | undefined): void;
 
 }
+
 /**
- * `DefaultPropertyViewWidgetProvider` should be extended to provide a new content property view widget for the given selection.
+ * The `DefaultPropertyViewWidgetProvider` is the default abstract implementation of the {@link PropertyViewWidgetProvider}
+ * and should be extended to provide a property view content widget for the given selection.
  */
 @injectable()
 export abstract class DefaultPropertyViewWidgetProvider implements PropertyViewWidgetProvider {

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

@@ -23,6 +23,11 @@ import { PropertyViewContentWidget } from './property-view-content-widget';
 import { PropertyViewService } from './property-view-service';
 import { nls } from '@theia/core/lib/common/nls';
 
+/**
+ * The main container for the selection-specific property widgets.
+ * Based on the given selection, the registered `PropertyViewWidgetProvider` provides the
+ * content widget that displays the corresponding properties.
+ */
 @injectable()
 export class PropertyViewWidget extends BaseWidget {
 

packages/property-view/src/browser/resource-property-view/resource-property-data-service.ts

@@ -22,6 +22,9 @@ import { FileStat } from '@theia/filesystem/lib/common/files';
 import { inject, injectable } from '@theia/core/shared/inversify';
 import { PropertyDataService } from '../property-data-service';
 
+/**
+ * This data service provides property data for {@link FileSelection}s and selections of {@link Navigatable}s.
+ */
 @injectable()
 export class ResourcePropertyDataService implements PropertyDataService {
 

packages/property-view/src/browser/resource-property-view/resource-property-view-tree-widget.tsx

@@ -35,6 +35,11 @@ import {
 } from './resource-property-view-tree-items';
 import { nls } from '@theia/core/lib/common/nls';
 
+/**
+ * This widget fetches the property data for {@link FileSelection}s and selections of {@link Navigatable}s
+ * and renders that property data as a {@link TreeWidget}.
+ * This widget is provided by the registered `ResourcePropertyViewWidgetProvider`.
+ */
 @injectable()
 export class ResourcePropertyViewTreeWidget extends TreeWidget implements PropertyViewContentWidget {
 

packages/property-view/src/browser/resource-property-view/resource-property-view-widget-provider.ts

@@ -20,6 +20,10 @@ import { inject, injectable } from '@theia/core/shared/inversify';
 import { DefaultPropertyViewWidgetProvider } from '../property-view-widget-provider';
 import { ResourcePropertyViewTreeWidget } from './resource-property-view-tree-widget';
 
+/**
+ * Provides the {@link ResourcePropertyViewTreeWidget} for
+ * {@link FileSelection}s and selections of {@link Navigatable}s.
+ */
 @injectable()
 export class ResourcePropertyViewWidgetProvider extends DefaultPropertyViewWidgetProvider {