From 04b19d7b63946ddbcfa115a0edc7ab37a91cd92c Mon Sep 17 00:00:00 2001 From: Nina Doschek Date: Thu, 14 Apr 2022 15:22:27 +0200 Subject: [PATCH] #11021 Add API documentation for property-view and selection-service - Add missing API documentation for interfaces and classes in the property-view package - Add missing API documentation for the Theia selection-service Resolves https://github.com/eclipse-theia/theia/issues/11021 Contributed on behalf of STMicroelectronics. Signed-off-by: Nina Doschek --- packages/core/src/common/selection-service.ts | 10 ++++++++-- .../browser/empty-property-view-widget-provider.tsx | 6 +++++- .../property-view/src/browser/property-data-service.ts | 2 +- .../src/browser/property-view-content-widget.ts | 5 +++++ .../property-view/src/browser/property-view-service.ts | 3 ++- .../src/browser/property-view-widget-provider.ts | 7 ++++++- .../property-view/src/browser/property-view-widget.tsx | 5 +++++ .../resource-property-data-service.ts | 3 +++ .../resource-property-view-tree-widget.tsx | 5 +++++ .../resource-property-view-widget-provider.ts | 4 ++++ 10 files changed, 44 insertions(+), 6 deletions(-) diff --git a/packages/core/src/common/selection-service.ts b/packages/core/src/common/selection-service.ts index 19731f6d78cef..28b99ec53eb13 100644 --- a/packages/core/src/common/selection-service.ts +++ b/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 { onSelectionChanged: Event; } +/** + * 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 { diff --git a/packages/property-view/src/browser/empty-property-view-widget-provider.tsx b/packages/property-view/src/browser/empty-property-view-widget-provider.tsx index ef0169c44d655..b420b9c87bfeb 100644 --- a/packages/property-view/src/browser/empty-property-view-widget-provider.tsx +++ b/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() diff --git a/packages/property-view/src/browser/property-data-service.ts b/packages/property-view/src/browser/property-data-service.ts index 935a3132d614a..f4a3e81725bb4 100644 --- a/packages/property-view/src/browser/property-data-service.ts +++ b/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; diff --git a/packages/property-view/src/browser/property-view-content-widget.ts b/packages/property-view/src/browser/property-view-content-widget.ts index 32f57af627114..91d6a72dcb553 100644 --- a/packages/property-view/src/browser/property-view-content-widget.ts +++ b/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; } diff --git a/packages/property-view/src/browser/property-view-service.ts b/packages/property-view/src/browser/property-view-service.ts index 9732470d4250f..58acf4e3961b6 100644 --- a/packages/property-view/src/browser/property-view-service.ts +++ b/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 { const provider = await this.prioritize(selection); diff --git a/packages/property-view/src/browser/property-view-widget-provider.ts b/packages/property-view/src/browser/property-view-widget-provider.ts index e40be75f778ce..31618432a0b8e 100644 --- a/packages/property-view/src/browser/property-view-widget-provider.ts +++ b/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 { diff --git a/packages/property-view/src/browser/property-view-widget.tsx b/packages/property-view/src/browser/property-view-widget.tsx index 7e2e313b3a951..bb9cd2f1601c8 100644 --- a/packages/property-view/src/browser/property-view-widget.tsx +++ b/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 { diff --git a/packages/property-view/src/browser/resource-property-view/resource-property-data-service.ts b/packages/property-view/src/browser/resource-property-view/resource-property-data-service.ts index b9376a34e46e1..55099a627e2ec 100644 --- a/packages/property-view/src/browser/resource-property-view/resource-property-data-service.ts +++ b/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 { diff --git a/packages/property-view/src/browser/resource-property-view/resource-property-view-tree-widget.tsx b/packages/property-view/src/browser/resource-property-view/resource-property-view-tree-widget.tsx index 7ff7cab71a1d1..ffeb1ce1c8b24 100644 --- a/packages/property-view/src/browser/resource-property-view/resource-property-view-tree-widget.tsx +++ b/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 { diff --git a/packages/property-view/src/browser/resource-property-view/resource-property-view-widget-provider.ts b/packages/property-view/src/browser/resource-property-view/resource-property-view-widget-provider.ts index 9dd6ad74ab11f..20a11e4275cdf 100644 --- a/packages/property-view/src/browser/resource-property-view/resource-property-view-widget-provider.ts +++ b/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 {