@codingame/monaco-vscode-api 20.1.0 → 20.2.0

package/vscode/src/vs/workbench/common/contributions.d.ts

@@ -1,29 +1,79 @@
 import { IConstructorSignature, ServicesAccessor, BrandedService } from "../../platform/instantiation/common/instantiation.js";
 import { LifecyclePhase } from "../services/lifecycle/common/lifecycle.js";
 import { Disposable } from "../../base/common/lifecycle.js";
+/**
+ * A workbench contribution that will be loaded when the workbench starts and disposed when the workbench shuts down.
+ */
 export interface IWorkbenchContribution {
 }
 export declare namespace Extensions {
+    /**
+     * @deprecated use `registerWorkbenchContribution2` instead.
+     */
     const Workbench = "workbench.contributions.kind";
 }
 export declare enum WorkbenchPhase {
+    /**
+     * 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 the other types, preferable
+     * `Lazy` to only instantiate the contribution when really needed.
+     */
     BlockStartup = 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 the other types, preferable
+     * `Lazy` to only instantiate the contribution when really needed.
+     */
     BlockRestore = 2,
+    /**
+     * Views, panels and editors have restored. Editors are given a bit of
+     * time to restore their contents.
+     */
     AfterRestored = 3,
+    /**
+     * The last phase after views, panels and editors have restored and
+     * some time has passed (2-5 seconds).
+     */
     Eventually = 4
 }
+/**
+ * A workbenchch contribution that will only be instantiated
+ * when calling `getWorkbenchContribution`.
+ */
 export interface ILazyWorkbenchContributionInstantiation {
     readonly lazy: true;
 }
+/**
+ * A workbench contribution that will be instantiated when the
+ * corresponding editor is being created.
+ */
 export interface IOnEditorWorkbenchContributionInstantiation {
     readonly editorTypeId: string;
 }
 export type WorkbenchContributionInstantiation = WorkbenchPhase | ILazyWorkbenchContributionInstantiation | IOnEditorWorkbenchContributionInstantiation;
 type IWorkbenchContributionSignature<Service extends BrandedService[]> = new (...services: Service) => IWorkbenchContribution;
 export interface IWorkbenchContributionsRegistry {
+    /**
+     * @deprecated use `registerWorkbenchContribution2` instead.
+     */
     registerWorkbenchContribution<Services extends BrandedService[]>(contribution: IWorkbenchContributionSignature<Services>, phase: LifecyclePhase.Restored | LifecyclePhase.Eventually): void;
+    /**
+     * Starts the registry by providing the required services.
+     */
     start(accessor: ServicesAccessor): void;
+    /**
+     * A promise that resolves when all contributions up to the `Restored`
+     * phase have been instantiated.
+     */
     readonly whenRestored: Promise<void>;
+    /**
+     * Provides access to the instantiation times of all contributions by
+     * lifecycle phase.
+     */
     readonly timings: Map<LifecyclePhase, Array<[
         string,
         number
@@ -63,8 +113,20 @@ export declare class WorkbenchContributionsRegistry extends Disposable implement
     private doInstantiateWhenIdle;
     private safeCreateContribution;
 }
+/**
+ * Register a workbench contribution that will be instantiated
+ * based on the `instantiation` property.
+ */
 export declare const registerWorkbenchContribution2: {
     <Services extends BrandedService[]>(id: string, ctor: IWorkbenchContributionSignature<Services>, instantiation: WorkbenchContributionInstantiation): void;
 };
+/**
+ * Provides access to a workbench contribution with a specific identifier.
+ * The contribution is created if not yet done.
+ *
+ * Note: will throw an error if
+ * - called too early before the registry has started
+ * - no contribution is known for the given identifier
+ */
 export declare const getWorkbenchContribution: <T extends IWorkbenchContribution>(id: string) => T;
 export {};

package/vscode/src/vs/workbench/common/editor/diffEditorInput.d.ts

@@ -4,6 +4,10 @@ import { EditorModel } from "./editorModel.js";
 import { Verbosity, IEditorDescriptor, IEditorPane, IResourceDiffEditorInput, IUntypedEditorInput, IDiffEditorInput, IResourceSideBySideEditorInput, EditorInputCapabilities } from "../editor.js";
 import { IInstantiationService } from "../../../platform/instantiation/common/instantiation.js";
 import { IEditorService } from "../../services/editor/common/editorService.service.js";
+/**
+ * The base editor input for the diff editor. It is made up of two editor inputs, the original version
+ * and the modified version.
+ */
 export declare class DiffEditorInput extends SideBySideEditorInput implements IDiffEditorInput {
     readonly original: EditorInput;
     readonly modified: EditorInput;

package/vscode/src/vs/workbench/common/editor/diffEditorModel.d.ts

@@ -1,5 +1,9 @@
 import { EditorModel } from "./editorModel.js";
 import { IResolvableEditorModel } from "../../../platform/editor/common/editor.js";
+/**
+ * The base editor model for the diff editor. It is made up of two editor models, the original version
+ * and the modified version.
+ */
 export declare class DiffEditorModel extends EditorModel {
     protected readonly _originalModel: IResolvableEditorModel | undefined;
     get originalModel(): IResolvableEditorModel | undefined;

package/vscode/src/vs/workbench/common/editor/editorInput.d.ts

@@ -6,51 +6,232 @@ import { IMarkdownString } from "../../../base/common/htmlContent.js";
 import { IDisposable } from "../../../base/common/lifecycle.js";
 import { ThemeIcon } from "../../../base/common/themables.js";
 export interface IEditorCloseHandler {
+    /**
+     * If `true`, will call into the `confirm` method to ask for confirmation
+     * before closing the editor.
+     */
     showConfirm(): boolean;
+    /**
+     * Allows an editor to control what should happen when the editor
+     * (or a list of editor of the same kind) is being closed.
+     *
+     * By default a file specific dialog will open if the editor is
+     * dirty and not in the process of saving.
+     *
+     * If the editor is not dealing with files or another condition
+     * should be used besides dirty state, this method should be
+     * implemented to show a different dialog.
+     *
+     * @param editors All editors of the same kind that are being closed. Should be used
+     * to show a combined dialog.
+     */
     confirm(editors: ReadonlyArray<IEditorIdentifier>): Promise<ConfirmResult>;
 }
 export interface IUntypedEditorOptions {
+    /**
+     * Implementations should try to preserve as much
+     * view state as possible from the typed input based
+     * on the group the editor is opened.
+     */
     readonly preserveViewState?: GroupIdentifier;
+    /**
+     * Implementations should preserve the original
+     * resource of the typed input and not alter
+     * it.
+     */
     readonly preserveResource?: boolean;
 }
+/**
+ * Editor inputs are lightweight objects that can be passed to the workbench API to open inside the editor part.
+ * Each editor input is mapped to an editor that is capable of opening it through the Platform facade.
+ */
 export declare abstract class EditorInput extends AbstractEditorInput {
     protected readonly _onDidChangeDirty: Emitter<void>;
     protected readonly _onDidChangeLabel: Emitter<void>;
     protected readonly _onDidChangeCapabilities: Emitter<void>;
     private readonly _onWillDispose;
+    /**
+     * Triggered when this input changes its dirty state.
+     */
     readonly onDidChangeDirty: import("../../../base/common/event.js").Event<void>;
+    /**
+     * Triggered when this input changes its label
+     */
     readonly onDidChangeLabel: import("../../../base/common/event.js").Event<void>;
+    /**
+     * Triggered when this input changes its capabilities.
+     */
     readonly onDidChangeCapabilities: import("../../../base/common/event.js").Event<void>;
+    /**
+     * Triggered when this input is about to be disposed.
+     */
     readonly onWillDispose: import("../../../base/common/event.js").Event<void>;
+    /**
+     * Optional: subclasses can override to implement
+     * custom confirmation on close behavior.
+     */
     readonly closeHandler?: IEditorCloseHandler;
+    /**
+     * Unique type identifier for this input. Every editor input of the
+     * same class should share the same type identifier. The type identifier
+     * is used for example for serialising/deserialising editor inputs
+     * via the serialisers of the `EditorInputFactoryRegistry`.
+     */
     abstract get typeId(): string;
+    /**
+     * Returns the optional associated resource of this input.
+     *
+     * This resource should be unique for all editors of the same
+     * kind and input and is often used to identify the editor input among
+     * others.
+     *
+     * **Note:** DO NOT use this property for anything but identity
+     * checks. DO NOT use this property to present as label to the user.
+     * Please refer to `EditorResourceAccessor` documentation in that case.
+     */
     abstract get resource(): URI | undefined;
+    /**
+     * Identifies the type of editor this input represents
+     * This ID is registered with the {@link EditorResolverService} to allow
+     * for resolving an untyped input to a typed one
+     */
     get editorId(): string | undefined;
+    /**
+     * The capabilities of the input.
+     */
     get capabilities(): EditorInputCapabilities;
+    /**
+     * Figure out if the input has the provided capability.
+     */
     hasCapability(capability: EditorInputCapabilities): boolean;
     isReadonly(): boolean | IMarkdownString;
+    /**
+     * Returns the display name of this input.
+     */
     getName(): string;
+    /**
+     * Returns the display description of this input.
+     */
     getDescription(verbosity?: Verbosity): string | undefined;
+    /**
+     * Returns the display title of this input.
+     */
     getTitle(verbosity?: Verbosity): string;
+    /**
+     * Returns the extra classes to apply to the label of this input.
+     */
     getLabelExtraClasses(): string[];
+    /**
+     * Returns the aria label to be read out by a screen reader.
+     */
     getAriaLabel(): string;
+    /**
+     * Returns the icon which represents this editor input.
+     * If undefined, the default icon will be used.
+     */
     getIcon(): ThemeIcon | undefined;
+    /**
+     * Returns a descriptor suitable for telemetry events.
+     *
+     * Subclasses should extend if they can contribute.
+     */
     getTelemetryDescriptor(): {
         [key: string]: unknown;
     };
+    /**
+     * Returns if this input is dirty or not.
+     */
     isDirty(): boolean;
+    /**
+     * Returns if the input has unsaved changes.
+     */
     isModified(): boolean;
+    /**
+     * Returns if this input is currently being saved or soon to be
+     * saved. Based on this assumption the editor may for example
+     * decide to not signal the dirty state to the user assuming that
+     * the save is scheduled to happen anyway.
+     */
     isSaving(): boolean;
+    /**
+     * Returns a type of `IDisposable` that represents the resolved input.
+     * Subclasses should override to provide a meaningful model or return
+     * `null` if the editor does not require a model.
+     *
+     * The `options` parameter are passed down from the editor when the
+     * input is resolved as part of it.
+     */
     resolve(): Promise<IDisposable | null>;
+    /**
+     * Saves the editor. The provided groupId helps implementors
+     * to e.g. preserve view state of the editor and re-open it
+     * in the correct group after saving.
+     *
+     * @returns the resulting editor input (typically the same) of
+     * this operation or `undefined` to indicate that the operation
+     * failed or was canceled.
+     */
     save(group: GroupIdentifier, options?: ISaveOptions): Promise<EditorInput | IUntypedEditorInput | undefined>;
+    /**
+     * Saves the editor to a different location. The provided `group`
+     * helps implementors to e.g. preserve view state of the editor
+     * and re-open it in the correct group after saving.
+     *
+     * @returns the resulting editor input (typically a different one)
+     * of this operation or `undefined` to indicate that the operation
+     * failed or was canceled.
+     */
     saveAs(group: GroupIdentifier, options?: ISaveOptions): Promise<EditorInput | IUntypedEditorInput | undefined>;
+    /**
+     * Reverts this input from the provided group.
+     */
     revert(group: GroupIdentifier, options?: IRevertOptions): Promise<void>;
+    /**
+     * Called to determine how to handle a resource that is renamed that matches
+     * the editors resource (or is a child of).
+     *
+     * Implementors are free to not implement this method to signal no intent
+     * to participate. If an editor is returned though, it will replace the
+     * current one with that editor and optional options.
+     */
     rename(group: GroupIdentifier, target: URI): Promise<IMoveResult | undefined>;
+    /**
+     * Returns a copy of the current editor input. Used when we can't just reuse the input
+     */
     copy(): EditorInput;
+    /**
+     * Indicates if this editor can be moved to another group. By default
+     * editors can freely be moved around groups. If an editor cannot be
+     * moved, a message should be returned to show to the user.
+     *
+     * @returns `true` if the editor can be moved to the target group, or
+     * a string with a message to show to the user if the editor cannot be
+     * moved.
+     */
     canMove(sourceGroup: GroupIdentifier, targetGroup: GroupIdentifier): true | string;
+    /**
+     * Returns if the other object matches this input.
+     */
     matches(otherInput: EditorInput | IUntypedEditorInput): boolean;
+    /**
+     * If a editor was registered onto multiple editor panes, this method
+     * will be asked to return the preferred one to use.
+     *
+     * @param editorPanes a list of editor pane descriptors that are candidates
+     * for the editor to open in.
+     */
     prefersEditorPane<T extends IEditorDescriptor<IEditorPane>>(editorPanes: T[]): T | undefined;
+    /**
+     * Returns a representation of this typed editor input as untyped
+     * resource editor input that e.g. can be used to serialize the
+     * editor input into a form that it can be restored.
+     *
+     * May return `undefined` if an untyped representation is not supported.
+     */
     toUntyped(options?: IUntypedEditorOptions): IUntypedEditorInput | undefined;
+    /**
+     * Returns if this editor is disposed.
+     */
     isDisposed(): boolean;
     dispose(): void;
 }

package/vscode/src/vs/workbench/common/editor/editorModel.d.ts

@@ -1,10 +1,27 @@
 import { Disposable } from "../../../base/common/lifecycle.js";
+/**
+ * The editor model is the heavyweight counterpart of editor input. Depending on the editor input, it
+ * resolves from a file system retrieve content and may allow for saving it back or reverting it.
+ * Editor models are typically cached for some while because they are expensive to construct.
+ */
 export declare class EditorModel extends Disposable {
     private readonly _onWillDispose;
     readonly onWillDispose: import("../../../base/common/event.js").Event<void>;
     private resolved;
+    /**
+     * Causes this model to resolve returning a promise when loading is completed.
+     */
     resolve(): Promise<void>;
+    /**
+     * Returns whether this model was loaded or not.
+     */
     isResolved(): boolean;
+    /**
+     * Find out if this model has been disposed.
+     */
     isDisposed(): boolean;
+    /**
+     * Subclasses should implement to free resources that have been claimed through loading.
+     */
     dispose(): void;
 }

package/vscode/src/vs/workbench/common/editor/sideBySideEditorInput.d.ts

@@ -4,6 +4,9 @@ import { IInstantiationService } from "../../../platform/instantiation/common/in
 import { EditorInputCapabilities, GroupIdentifier, ISaveOptions, IRevertOptions, IEditorSerializer, ISideBySideEditorInput, IUntypedEditorInput, IResourceSideBySideEditorInput, IMoveResult, Verbosity } from "../editor.js";
 import { EditorInput, IUntypedEditorOptions } from "./editorInput.js";
 import { IEditorService } from "../../services/editor/common/editorService.service.js";
+/**
+ * Side by side editor inputs that have a primary and secondary side.
+ */
 export declare class SideBySideEditorInput extends EditorInput implements ISideBySideEditorInput {
     protected readonly preferredName: string | undefined;
     protected readonly preferredDescription: string | undefined;

package/vscode/src/vs/workbench/common/editor/textDiffEditorModel.d.ts

@@ -2,6 +2,10 @@ import { IDiffEditorModel } from "../../../editor/common/editorCommon.js";
 import { BaseTextEditorModel } from "./textEditorModel.js";
 import { DiffEditorModel } from "./diffEditorModel.js";
 import { IMarkdownString } from "../../../base/common/htmlContent.js";
+/**
+ * The base text editor model for the diff editor. It is made up of two text editor models, the original version
+ * and the modified version.
+ */
 export declare class TextDiffEditorModel extends DiffEditorModel {
     protected readonly _originalModel: BaseTextEditorModel | undefined;
     get originalModel(): BaseTextEditorModel | undefined;

package/vscode/src/vs/workbench/common/editor/textEditorModel.d.ts

@@ -10,6 +10,9 @@ import { ILanguageDetectionService } from "../../services/languageDetection/comm
 import { IAccessibilityService } from "../../../platform/accessibility/common/accessibility.service.js";
 import { IMarkdownString } from "../../../base/common/htmlContent.js";
 import { TextModelEditSource } from "../../../editor/common/textModelEditSource.js";
+/**
+ * The base text editor model leverages the code editor model. This class is only intended to be subclassed and not instantiated.
+ */
 export declare class BaseTextEditorModel extends EditorModel implements ITextEditorModel, ILanguageSupport {
     protected modelService: IModelService;
     protected languageService: ILanguageService;
@@ -35,10 +38,22 @@ export declare class BaseTextEditorModel extends EditorModel implements ITextEdi
     getLanguageId(): string | undefined;
     protected autoDetectLanguage(): Promise<void>;
     private doAutoDetectLanguage;
+    /**
+     * Creates the text editor model with the provided value, optional preferred language
+     * (can be comma separated for multiple values) and optional resource URL.
+     */
     protected createTextEditorModel(value: ITextBufferFactory, resource: URI | undefined, preferredLanguageId?: string): ITextModel;
     private doCreateTextEditorModel;
     protected getFirstLineText(value: ITextBufferFactory | ITextModel): string;
+    /**
+     * Gets the language for the given identifier. Subclasses can override to provide their own implementation of this lookup.
+     *
+     * @param firstLineText optional first line of the text buffer to set the language on. This can be used to guess a language from content.
+     */
     protected getOrCreateLanguage(resource: URI | undefined, languageService: ILanguageService, preferredLanguage: string | undefined, firstLineText?: string): ILanguageSelection;
+    /**
+     * Updates the text editor model with the provided value. If the value is the same as the model has, this is a no-op.
+     */
     updateTextEditorModel(newValue?: ITextBufferFactory, preferredLanguageId?: string, reason?: TextModelEditSource): void;
     createSnapshot(this: IResolvedTextEditorModel): ITextSnapshot;
     createSnapshot(this: ITextEditorModel): ITextSnapshot | null;