Document webview view service

src/vs/workbench/contrib/webviewView/browser/webviewViewService.ts

@@ -10,35 +10,84 @@ import { createDecorator } from 'vs/platform/instantiation/common/instantiation'
 import { IViewBadge } from 'vs/workbench/common/views';
 import { IOverlayWebview } from 'vs/workbench/contrib/webview/browser/webview';
 
-export const IWebviewViewService = createDecorator<IWebviewViewService>('webviewViewService');
-
+/**
+ * A webview shown in a view pane.
+ */
 export interface WebviewView {
+	/**
+	 * The text displayed in the view's title.
+	 */
 	title?: string;
+
+	/**
+	 * Additional text shown for this view.
+	 */
 	description?: string;
+
+	/**
+	 * The badge shown for this view.
+	 */
 	badge?: IViewBadge;
 
+	/**
+	 * The webview associated with this webview view.
+	 */
 	readonly webview: IOverlayWebview;
 
+	/**
+	 * Fired when the visibility of the webview view changes.
+	 *
+	 * This can happen when the view itself is hidden, when the view is collapsed, or when the user switches away from
+	 * the view.
+	 */
 	readonly onDidChangeVisibility: Event<boolean>;
+
+	/**
+	 * Fired when the webview view has been disposed of.
+	 */
 	readonly onDispose: Event<void>;
 
+	/**
+	 * Dispose of the webview view and clean up any associated resources.
+	 */
 	dispose(): void;
 
+	/**
+	 * Force the webview view to show.
+	 */
 	show(preserveFocus: boolean): void;
 }
 
+/**
+ * Fill in the contents of a newly created webview view.
+ */
 export interface IWebviewViewResolver {
+	/**
+	 * Fill in the contents of a webview view.
+	 */
 	resolve(webviewView: WebviewView, cancellation: CancellationToken): Promise<void>;
 }
 
+export const IWebviewViewService = createDecorator<IWebviewViewService>('webviewViewService');
+
 export interface IWebviewViewService {
 
 	readonly _serviceBrand: undefined;
 
+	/**
+	 * Fired when a resolver has been registered
+	 */
 	readonly onNewResolverRegistered: Event<{ readonly viewType: string }>;
 
-	register(type: string, resolver: IWebviewViewResolver): IDisposable;
+	/**
+	 * Register a new {@link IWebviewViewResolver webview view resolver}.
+	 */
+	register(viewType: string, resolver: IWebviewViewResolver): IDisposable;
 
+	/**
+	 * Try to resolve a webview view. The promise will not resolve until a resolver for the webview has been registered
+	 * and run
+	 */
 	resolve(viewType: string, webview: WebviewView, cancellation: CancellationToken): Promise<void>;
 }
 
@@ -48,7 +97,7 @@ export class WebviewViewService extends Disposable implements IWebviewViewServic
 
 	private readonly _resolvers = new Map<string, IWebviewViewResolver>();
 
-	private readonly _awaitingRevival = new Map<string, { webview: WebviewView; resolve: () => void }>();
+	private readonly _awaitingRevival = new Map<string, { readonly webview: WebviewView; readonly resolve: () => void }>();
 
 	private readonly _onNewResolverRegistered = this._register(new Emitter<{ readonly viewType: string }>());
 	public readonly onNewResolverRegistered = this._onNewResolverRegistered.event;
@@ -90,4 +139,3 @@ export class WebviewViewService extends Disposable implements IWebviewViewServic
 		return resolver.resolve(webview, cancellation);
 	}
 }
-