@codingame/monaco-vscode-api 20.1.1 → 20.2.1

package/vscode/src/vs/workbench/services/lifecycle/common/lifecycle.d.ts

@@ -1,17 +1,63 @@
 import { CancellationToken } from "../../../../base/common/cancellation.js";
+/**
+ * An event that is send out when the window is about to close. Clients have a chance to veto
+ * the closing by either calling veto with a boolean "true" directly or with a promise that
+ * resolves to a boolean. Returning a promise is useful in cases of long running operations
+ * on shutdown.
+ *
+ * Note: It is absolutely important to avoid long running promises if possible. Please try hard
+ * to return a boolean directly. Returning a promise has quite an impact on the shutdown sequence!
+ */
 export interface BeforeShutdownEvent {
+    /**
+     * The reason why the application will be shutting down.
+     */
     readonly reason: ShutdownReason;
+    /**
+     * Allows to veto the shutdown. The veto can be a long running operation but it
+     * will block the application from closing.
+     *
+     * @param id to identify the veto operation in case it takes very long or never
+     * completes.
+     */
     veto(value: boolean | Promise<boolean>, id: string): void;
 }
 export interface InternalBeforeShutdownEvent extends BeforeShutdownEvent {
+    /**
+     * Allows to set a veto operation to run after all other
+     * vetos have been handled from the `BeforeShutdownEvent`
+     *
+     * This method is hidden from the API because it is intended
+     * to be only used once internally.
+     */
     finalVeto(vetoFn: () => boolean | Promise<boolean>, id: string): void;
 }
+/**
+ * An event that signals an error happened during `onBeforeShutdown` veto handling.
+ * In this case the shutdown operation will not proceed because this is an unexpected
+ * condition that is treated like a veto.
+ */
 export interface BeforeShutdownErrorEvent {
+    /**
+     * The reason why the application is shutting down.
+     */
     readonly reason: ShutdownReason;
+    /**
+     * The error that happened during shutdown handling.
+     */
     readonly error: Error;
 }
 export declare enum WillShutdownJoinerOrder {
+    /**
+     * Joiners to run before the `Last` joiners. This is the default order and best for
+     * most cases. You can be sure that services are still functional at this point.
+     */
     Default = 1,
+    /**
+     * The joiners to run last. This should ONLY be used in rare cases when you have no
+     * dependencies to workbench services or state. The workbench may be in a state where
+     * resources can no longer be accessed or changed.
+     */
     Last = 2
 }
 export interface IWillShutdownEventJoiner {
@@ -25,18 +71,68 @@ export interface IWillShutdownEventDefaultJoiner extends IWillShutdownEventJoine
 export interface IWillShutdownEventLastJoiner extends IWillShutdownEventJoiner {
     readonly order: WillShutdownJoinerOrder.Last;
 }
+/**
+ * An event that is send out when the window closes. Clients have a chance to join the closing
+ * by providing a promise from the join method. Returning a promise is useful in cases of long
+ * running operations on shutdown.
+ *
+ * Note: It is absolutely important to avoid long running promises if possible. Please try hard
+ * to return a boolean directly. Returning a promise has quite an impact on the shutdown sequence!
+ */
 export interface WillShutdownEvent {
+    /**
+     * The reason why the application is shutting down.
+     */
     readonly reason: ShutdownReason;
+    /**
+     * A token that will signal cancellation when the
+     * shutdown was forced by the user.
+     */
     readonly token: CancellationToken;
+    /**
+     * Allows to join the shutdown. The promise can be a long running operation but it
+     * will block the application from closing.
+     *
+     * @param promise the promise to join the shutdown event.
+     * @param joiner to identify the join operation in case it takes very long or never
+     * completes.
+     */
     join(promise: Promise<void>, joiner: IWillShutdownEventDefaultJoiner): void;
+    /**
+     * Allows to join the shutdown at the end. The promise can be a long running operation but it
+     * will block the application from closing.
+     *
+     * @param promiseFn the promise to join the shutdown event.
+     * @param joiner to identify the join operation in case it takes very long or never
+     * completes.
+     */
     join(promiseFn: (() => Promise<void>), joiner: IWillShutdownEventLastJoiner): void;
+    /**
+     * Allows to access the joiners that have not finished joining this event.
+     */
     joiners(): IWillShutdownEventJoiner[];
+    /**
+     * Allows to enforce the shutdown, even when there are
+     * pending `join` operations to complete.
+     */
     force(): void;
 }
 export declare enum ShutdownReason {
+    /**
+     * The window is closed.
+     */
     CLOSE = 1,
+    /**
+     * The window closes because the application quits.
+     */
     QUIT = 2,
+    /**
+     * The window is reloaded.
+     */
     RELOAD = 3,
+    /**
+     * The window is loaded into a different workspace context.
+     */
     LOAD = 4
 }
 export declare enum StartupKind {
@@ -46,9 +142,29 @@ export declare enum StartupKind {
 }
 export declare function StartupKindToString(startupKind: StartupKind): string;
 export declare enum LifecyclePhase {
+    /**
+     * The first phase signals that we are about to startup getting ready.
+     *
+     * Note: doing work in this phase blocks an editor from showing to
+     * the user, so please rather consider to use `Restored` phase.
+     */
     Starting = 1,
+    /**
+     * Services are ready and the window is about to restore its UI state.
+     *
+     * Note: doing work in this phase blocks an editor from showing to
+     * the user, so please rather consider to use `Restored` phase.
+     */
     Ready = 2,
+    /**
+     * Views, panels and editors have restored. Editors are given a bit of
+     * time to restore their contents.
+     */
     Restored = 3,
+    /**
+     * The last phase after views, panels and editors have restored and
+     * some time has passed (2-5 seconds).
+     */
     Eventually = 4
 }
 export declare function LifecyclePhaseToString(phase: LifecyclePhase): string;

package/vscode/src/vs/workbench/services/lifecycle/common/lifecycle.service.d.ts

@@ -1,16 +1,70 @@
 import { Event } from "../../../../base/common/event.js";
 import { StartupKind, LifecyclePhase, BeforeShutdownEvent, BeforeShutdownErrorEvent, WillShutdownEvent } from "./lifecycle.js";
 export declare const ILifecycleService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<ILifecycleService>;
+/**
+* A lifecycle service informs about lifecycle events of the
+* application, such as shutdown.
+*/
 export interface ILifecycleService {
     readonly _serviceBrand: undefined;
+    /**
+    * Value indicates how this window got loaded.
+    */
     readonly startupKind: StartupKind;
+    /**
+    * A flag indicating in what phase of the lifecycle we currently are.
+    */
     phase: LifecyclePhase;
+    /**
+    * Fired before shutdown happens. Allows listeners to veto against the
+    * shutdown to prevent it from happening.
+    *
+    * The event carries a shutdown reason that indicates how the shutdown was triggered.
+    */
     readonly onBeforeShutdown: Event<BeforeShutdownEvent>;
+    /**
+    * Fired when the shutdown was prevented by a component giving veto.
+    */
     readonly onShutdownVeto: Event<void>;
+    /**
+    * Fired when an error happened during `onBeforeShutdown` veto handling.
+    * In this case the shutdown operation will not proceed because this is
+    * an unexpected condition that is treated like a veto.
+    *
+    * The event carries a shutdown reason that indicates how the shutdown was triggered.
+    */
     readonly onBeforeShutdownError: Event<BeforeShutdownErrorEvent>;
+    /**
+    * Fired when no client is preventing the shutdown from happening (from `onBeforeShutdown`).
+    *
+    * This event can be joined with a long running operation via `WillShutdownEvent#join()` to
+    * handle long running shutdown operations.
+    *
+    * The event carries a shutdown reason that indicates how the shutdown was triggered.
+    */
     readonly onWillShutdown: Event<WillShutdownEvent>;
+    /**
+    * A flag indicating that we are about to shutdown without further veto.
+    */
     readonly willShutdown: boolean;
+    /**
+    * Fired when the shutdown is about to happen after long running shutdown operations
+    * have finished (from `onWillShutdown`).
+    *
+    * This event should be used to dispose resources.
+    */
     readonly onDidShutdown: Event<void>;
+    /**
+    * Returns a promise that resolves when a certain lifecycle phase
+    * has started.
+    */
     when(phase: LifecyclePhase): Promise<void>;
+    /**
+    * Triggers a shutdown of the workbench. Depending on native or web, this can have
+    * different implementations and behaviour.
+    *
+    * **Note:** this should normally not be called. See related methods in `IHostService`
+    * and `INativeHostService` to close a window or quit the application.
+    */
     shutdown(): Promise<void>;
 }

package/vscode/src/vs/workbench/services/lifecycle/common/lifecycleService.d.ts

@@ -32,5 +32,8 @@ export declare abstract class AbstractLifecycleService extends Disposable implem
     protected doResolveStartupKind(): StartupKind | undefined;
     set phase(value: LifecyclePhase);
     when(phase: LifecyclePhase): Promise<void>;
+    /**
+     * Subclasses to implement the explicit shutdown method.
+     */
     abstract shutdown(): Promise<void>;
 }

package/vscode/src/vs/workbench/services/output/common/output.d.ts

@@ -3,10 +3,25 @@ import { URI } from "../../../../base/common/uri.js";
 import { RawContextKey } from "../../../../platform/contextkey/common/contextkey.js";
 import { LogLevel } from "../../../../platform/log/common/log.js";
 import { Range } from "../../../../editor/common/core/range.js";
+/**
+ * Mime type used by the output editor.
+ */
 export declare const OUTPUT_MIME = "text/x-code-output";
+/**
+ * Id used by the output editor.
+ */
 export declare const OUTPUT_MODE_ID = "Log";
+/**
+ * Mime type used by the log output editor.
+ */
 export declare const LOG_MIME = "text/x-code-log-output";
+/**
+ * Id used by the log output editor.
+ */
 export declare const LOG_MODE_ID = "log";
+/**
+ * Output view id
+ */
 export declare const OUTPUT_VIEW_ID = "workbench.panel.output";
 export declare const CONTEXT_IN_OUTPUT: RawContextKey<boolean>;
 export declare const CONTEXT_ACTIVE_FILE_OUTPUT: RawContextKey<boolean>;
@@ -49,15 +64,42 @@ export interface ILogEntry {
     readonly category: string | undefined;
 }
 export interface IOutputChannel {
+    /**
+     * Identifier of the output channel.
+     */
     readonly id: string;
+    /**
+     * Label of the output channel to be displayed to the user.
+     */
     readonly label: string;
+    /**
+     * URI of the output channel.
+     */
     readonly uri: URI;
+    /**
+     * Log entries of the output channel.
+     */
     getLogEntries(): readonly ILogEntry[];
+    /**
+     * Appends output to the channel.
+     */
     append(output: string): void;
+    /**
+     * Clears all received output for this channel.
+     */
     clear(): void;
+    /**
+     * Replaces the content of the channel with given output
+     */
     replace(output: string): void;
+    /**
+     * Update the channel.
+     */
     update(mode: OutputChannelUpdateMode.Append): void;
     update(mode: OutputChannelUpdateMode, till: number): void;
+    /**
+     * Disposes the output channel.
+     */
     dispose(): void;
 }
 export declare const Extensions: {
@@ -88,9 +130,24 @@ export interface IOutputChannelRegistry {
     readonly onDidRegisterChannel: Event<string>;
     readonly onDidRemoveChannel: Event<IOutputChannelDescriptor>;
     readonly onDidUpdateChannelSources: Event<IMultiSourceOutputChannelDescriptor>;
+    /**
+     * Make an output channel known to the output world.
+     */
     registerChannel(descriptor: IOutputChannelDescriptor): void;
+    /**
+     * Update the files for the given output channel.
+     */
     updateChannelSources(id: string, sources: IOutputContentSource[]): void;
+    /**
+     * Returns the list of channels known to the output world.
+     */
     getChannels(): IOutputChannelDescriptor[];
+    /**
+     * Returns the channel with the passed id.
+     */
     getChannel(id: string): IOutputChannelDescriptor | undefined;
+    /**
+     * Remove the output channel with the passed id.
+     */
     removeChannel(id: string): void;
 }

package/vscode/src/vs/workbench/services/output/common/output.service.d.ts

@@ -2,18 +2,63 @@ import { Event } from "../../../../base/common/event.js";
 import { LogLevel } from "../../../../platform/log/common/log.js";
 import { IOutputViewFilters, IOutputChannel, IOutputChannelDescriptor } from "./output.js";
 export declare const IOutputService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IOutputService>;
+/**
+* The output service to manage output from the various processes running.
+*/
 export interface IOutputService {
     readonly _serviceBrand: undefined;
+    /**
+    *  Output view filters.
+    */
     readonly filters: IOutputViewFilters;
+    /**
+    * Given the channel id returns the output channel instance.
+    * Channel should be first registered via OutputChannelRegistry.
+    */
     getChannel(id: string): IOutputChannel | undefined;
+    /**
+    * Given the channel id returns the registered output channel descriptor.
+    */
     getChannelDescriptor(id: string): IOutputChannelDescriptor | undefined;
+    /**
+    * Returns an array of all known output channels descriptors.
+    */
     getChannelDescriptors(): IOutputChannelDescriptor[];
+    /**
+    * Returns the currently active channel.
+    * Only one channel can be active at a given moment.
+    */
     getActiveChannel(): IOutputChannel | undefined;
+    /**
+    * Show the channel with the passed id.
+    */
     showChannel(id: string, preserveFocus?: boolean): Promise<void>;
+    /**
+    * Allows to register on active output channel change.
+    */
     onActiveOutputChannel: Event<string>;
+    /**
+    * Register a compound log channel with the given channels.
+    */
     registerCompoundLogChannel(channels: IOutputChannelDescriptor[]): string;
+    /**
+    * Save the logs to a file.
+    */
     saveOutputAs(...channels: IOutputChannelDescriptor[]): Promise<void>;
+    /**
+    * Checks if the log level can be set for the given channel.
+    * @param channel
+    */
     canSetLogLevel(channel: IOutputChannelDescriptor): boolean;
+    /**
+    * Returns the log level for the given channel.
+    * @param channel
+    */
     getLogLevel(channel: IOutputChannelDescriptor): LogLevel | undefined;
+    /**
+    * Sets the log level for the given channel.
+    * @param channel
+    * @param logLevel
+    */
     setLogLevel(channel: IOutputChannelDescriptor, logLevel: LogLevel): void;
 }

package/vscode/src/vs/workbench/services/panecomposite/browser/panecomposite.service.d.ts

@@ -14,14 +14,44 @@ export interface IPaneCompositePartService {
         composite: IPaneComposite;
         viewContainerLocation: ViewContainerLocation;
     }>;
+    /**
+    * Opens a viewlet with the given identifier and pass keyboard focus to it if specified.
+    */
     openPaneComposite(id: string | undefined, viewContainerLocation: ViewContainerLocation, focus?: boolean): Promise<IPaneComposite | undefined>;
+    /**
+    * Returns the current active viewlet if any.
+    */
     getActivePaneComposite(viewContainerLocation: ViewContainerLocation): IPaneComposite | undefined;
+    /**
+    * Returns the viewlet by id.
+    */
     getPaneComposite(id: string, viewContainerLocation: ViewContainerLocation): PaneCompositeDescriptor | undefined;
+    /**
+    * Returns all enabled viewlets
+    */
     getPaneComposites(viewContainerLocation: ViewContainerLocation): PaneCompositeDescriptor[];
+    /**
+    * Returns id of pinned view containers following the visual order.
+    */
     getPinnedPaneCompositeIds(viewContainerLocation: ViewContainerLocation): string[];
+    /**
+    * Returns id of visible view containers following the visual order.
+    */
     getVisiblePaneCompositeIds(viewContainerLocation: ViewContainerLocation): string[];
+    /**
+    * Returns id of all view containers following visual order.
+    */
     getPaneCompositeIds(viewContainerLocation: ViewContainerLocation): string[];
+    /**
+    * Returns the progress indicator for the side bar.
+    */
     getProgressIndicator(id: string, viewContainerLocation: ViewContainerLocation): IProgressIndicator | undefined;
+    /**
+    * Hide the active viewlet.
+    */
     hideActivePaneComposite(viewContainerLocation: ViewContainerLocation): void;
+    /**
+    * Return the last active viewlet id.
+    */
     getLastActivePaneCompositeId(viewContainerLocation: ViewContainerLocation): string;
 }

package/vscode/src/vs/workbench/services/path/common/pathService.service.d.ts

@@ -2,18 +2,60 @@ import { IPath } from "../../../../base/common/path.js";
 import { OperatingSystem } from "../../../../base/common/platform.js";
 import { URI } from "../../../../base/common/uri.js";
 export declare const IPathService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IPathService>;
+/**
+* Provides access to path related properties that will match the
+* environment. If the environment is connected to a remote, the
+* path properties will match that of the remotes operating system.
+*/
 export interface IPathService {
     readonly _serviceBrand: undefined;
+    /**
+    * The correct path library to use for the target environment. If
+    * the environment is connected to a remote, this will be the
+    * path library of the remote file system. Otherwise it will be
+    * the local file system's path library depending on the OS.
+    */
     readonly path: Promise<IPath>;
+    /**
+    * Determines the best default URI scheme for the current workspace.
+    * It uses information about whether we're running remote, in browser,
+    * or native combined with information about the current workspace to
+    * find the best default scheme.
+    */
     readonly defaultUriScheme: string;
+    /**
+    * Converts the given path to a file URI to use for the target
+    * environment. If the environment is connected to a remote, it
+    * will use the path separators according to the remote file
+    * system. Otherwise it will use the local file system's path
+    * separators.
+    */
     fileURI(path: string): Promise<URI>;
+    /**
+    * Resolves the user-home directory for the target environment.
+    * If the envrionment is connected to a remote, this will be the
+    * remote's user home directory, otherwise the local one unless
+    * `preferLocal` is set to `true`.
+    */
     userHome(options: {
         preferLocal: true;
     }): URI;
     userHome(options?: {
         preferLocal: boolean;
     }): Promise<URI>;
+    /**
+    * Figures out if the provided resource has a valid file name
+    * for the operating system the file is saved to.
+    *
+    * Note: this currently only supports `file` and `vscode-file`
+    * protocols where we know the limits of the file systems behind
+    * these OS. Other remotes are not supported and this method
+    * will always return `true` for them.
+    */
     hasValidBasename(resource: URI, basename?: string): Promise<boolean>;
     hasValidBasename(resource: URI, os: OperatingSystem, basename?: string): boolean;
+    /**
+    * @deprecated use `userHome` instead.
+    */
     readonly resolvedUserHome: URI | undefined;
 }

package/vscode/src/vs/workbench/services/remote/common/remoteAgentService.service.d.ts

@@ -6,10 +6,26 @@ export declare const IRemoteAgentService: import("../../../../platform/instantia
 export interface IRemoteAgentService {
     readonly _serviceBrand: undefined;
     getConnection(): IRemoteAgentConnection | null;
+    /**
+    * Get the remote environment. In case of an error, returns `null`.
+    */
     getEnvironment(): Promise<IRemoteAgentEnvironment | null>;
+    /**
+    * Get the remote environment. Can return an error.
+    */
     getRawEnvironment(): Promise<IRemoteAgentEnvironment | null>;
+    /**
+    * Get exit information for a remote extension host.
+    */
     getExtensionHostExitInfo(reconnectionToken: string): Promise<IExtensionHostExitInfo | null>;
+    /**
+    * Gets the round trip time from the remote extension host. Note that this
+    * may be delayed if the extension host is busy.
+    */
     getRoundTripTime(): Promise<number | undefined>;
+    /**
+    * Gracefully ends the current connection, if any.
+    */
     endConnection(): Promise<void>;
     getDiagnosticInfo(options: IDiagnosticInfoOptions): Promise<IDiagnosticInfo | undefined>;
     updateTelemetryLevel(telemetryLevel: TelemetryLevel): Promise<void>;

package/vscode/src/vs/workbench/services/search/common/folderQuerySearchTree.d.ts

@@ -1,6 +1,10 @@
 import { URI } from "../../../../base/common/uri.js";
 import { IFolderQuery } from "./search.js";
 import { TernarySearchTree } from "../../../../base/common/ternarySearchTree.js";
+/**
+ * A ternary search tree that supports URI keys and query/fragment-aware substring matching, specifically for file search.
+ * This is because the traditional TST does not support query and fragments https://github.com/microsoft/vscode/issues/227836
+ */
 export declare class FolderQuerySearchTree<FolderQueryInfo extends {
     folder: URI;
 }> extends TernarySearchTree<URI, Map<string, FolderQueryInfo>> {

package/vscode/src/vs/workbench/services/search/common/queryBuilder.d.ts

@@ -9,6 +9,9 @@ import { IEditorGroupsService } from "../../editor/common/editorGroupsService.se
 import { IPathService } from "../../path/common/pathService.service.js";
 import { IAITextQuery, IFileQuery, IPatternInfo, ITextQuery, ITextSearchPreviewOptions } from "./search.js";
 import { GlobPattern } from "./searchExtTypes.js";
+/**
+ * One folder to search and a set of glob expressions that should be applied.
+ */
 export interface ISearchPathPattern {
     searchPath: uri;
     pattern?: glob.IExpression;
@@ -20,6 +23,9 @@ export interface ISearchPatternBuilder<U extends UriComponents> {
 }
 export declare function isISearchPatternBuilder<U extends UriComponents>(object: ISearchPatternBuilder<U> | ISearchPathPatternBuilder): object is ISearchPatternBuilder<U>;
 export declare function globPatternToISearchPatternBuilder(globPattern: GlobPattern): ISearchPatternBuilder<URI>;
+/**
+ * A set of search paths and a set of glob expressions that should be applied.
+ */
 export interface ISearchPathsInfo {
     searchPaths?: ISearchPathPattern[];
     pattern?: glob.IExpression;
@@ -29,6 +35,7 @@ interface ICommonQueryBuilderOptions<U extends UriComponents = URI> {
     excludePattern?: ISearchPatternBuilder<U>[];
     includePattern?: ISearchPathPatternBuilder;
     extraFileResources?: U[];
+    /** Parse the special ./ syntax supported by the searchview, and expand foo to ** /foo */
     expandPatterns?: boolean;
     maxResults?: number;
     maxFileSize?: number;
@@ -70,20 +77,41 @@ export declare class QueryBuilder {
     constructor(configurationService: IConfigurationService, workspaceContextService: IWorkspaceContextService, editorGroupsService: IEditorGroupsService, logService: ILogService, pathService: IPathService, uriIdentityService: IUriIdentityService);
     aiText(contentPattern: string, folderResources?: uri[], options?: ITextQueryBuilderOptions): IAITextQuery;
     text(contentPattern: IPatternInfo, folderResources?: uri[], options?: ITextQueryBuilderOptions): ITextQuery;
+    /**
+     * Adjusts input pattern for config
+     */
     private getContentPattern;
     file(folders: (IWorkspaceFolderData | URI)[], options?: IFileQueryBuilderOptions): IFileQuery;
     private handleIncludeExclude;
     private commonQuery;
     private commonQueryFromFileList;
+    /**
+     * Resolve isCaseSensitive flag based on the query and the isSmartCase flag, for search providers that don't support smart case natively.
+     */
     private isCaseSensitive;
     private isMultiline;
+    /**
+     * Take the includePattern as seen in the search viewlet, and split into components that look like searchPaths, and
+     * glob patterns. Glob patterns are expanded from 'foo/bar' to '{foo/bar/**, **\/foo/bar}.
+     *
+     * Public for test.
+     */
     parseSearchPaths(pattern: string | string[]): ISearchPathsInfo;
     private getExcludesForFolder;
+    /**
+     * Split search paths (./ or ../ or absolute paths in the includePatterns) into absolute paths and globs applied to those paths
+     */
     private expandSearchPathPatterns;
+    /**
+     * Takes a searchPath like `./a/foo` or `../a/foo` and expands it to absolute paths for all the workspaces it matches.
+     */
     private expandOneSearchPath;
     private resolveOneSearchPathPattern;
     private getFolderQueryForSearchPath;
     private getFolderQueryForRoot;
 }
+/**
+ * Construct an include pattern from a list of folders uris to search in.
+ */
 export declare function resolveResourcesForSearchIncludes(resources: URI[], contextService: IWorkspaceContextService): string[];
 export {};