@codingame/monaco-vscode-api 20.1.1 → 20.2.0

package/vscode/src/vs/editor/common/editorCommon.d.ts

@@ -11,30 +11,100 @@ import { ISelection, Selection } from "./core/selection.js";
 import { IModelDecoration, IModelDecorationsChangeAccessor, IModelDeltaDecoration, ITextModel, IValidEditOperation, OverviewRulerLane, TrackedRangeStickiness } from "./model.js";
 import { IModelDecorationsChangedEvent } from "./textModelEvents.js";
 import { ICommandMetadata } from "../../platform/commands/common/commands.js";
+/**
+ * A builder and helper for edit operations for a command.
+ */
 export interface IEditOperationBuilder {
+    /**
+     * Add a new edit operation (a replace operation).
+     * @param range The range to replace (delete). May be empty to represent a simple insert.
+     * @param text The text to replace with. May be null to represent a simple delete.
+     */
     addEditOperation(range: IRange, text: string | null, forceMoveMarkers?: boolean): void;
+    /**
+     * Add a new edit operation (a replace operation).
+     * The inverse edits will be accessible in `ICursorStateComputerData.getInverseEditOperations()`
+     * @param range The range to replace (delete). May be empty to represent a simple insert.
+     * @param text The text to replace with. May be null to represent a simple delete.
+     */
     addTrackedEditOperation(range: IRange, text: string | null, forceMoveMarkers?: boolean): void;
+    /**
+     * Track `selection` when applying edit operations.
+     * A best effort will be made to not grow/expand the selection.
+     * An empty selection will clamp to a nearby character.
+     * @param selection The selection to track.
+     * @param trackPreviousOnEmpty If set, and the selection is empty, indicates whether the selection
+     *           should clamp to the previous or the next character.
+     * @return A unique identifier.
+     */
     trackSelection(selection: Selection, trackPreviousOnEmpty?: boolean): string;
 }
+/**
+ * A helper for computing cursor state after a command.
+ */
 export interface ICursorStateComputerData {
+    /**
+     * Get the inverse edit operations of the added edit operations.
+     */
     getInverseEditOperations(): IValidEditOperation[];
+    /**
+     * Get a previously tracked selection.
+     * @param id The unique identifier returned by `trackSelection`.
+     * @return The selection.
+     */
     getTrackedSelection(id: string): Selection;
 }
+/**
+ * A command that modifies text / cursor state on a model.
+ */
 export interface ICommand {
+    /**
+     * Signal that this command is inserting automatic whitespace that should be trimmed if possible.
+     * @internal
+     */
     readonly insertsAutoWhitespace?: boolean;
+    /**
+     * Get the edit operations needed to execute this command.
+     * @param model The model the command will execute on.
+     * @param builder A helper to collect the needed edit operations and to track selections.
+     */
     getEditOperations(model: ITextModel, builder: IEditOperationBuilder): void;
+    /**
+     * Compute the cursor state after the edit operations were applied.
+     * @param model The model the command has executed on.
+     * @param helper A helper to get inverse edit operations and to get previously tracked selections.
+     * @return The cursor state after the command executed.
+     */
     computeCursorState(model: ITextModel, helper: ICursorStateComputerData): Selection;
 }
+/**
+ * A model for the diff editor.
+ */
 export interface IDiffEditorModel {
+    /**
+     * Original model.
+     */
     original: ITextModel;
+    /**
+     * Modified model.
+     */
     modified: ITextModel;
 }
 export interface IDiffEditorViewModel extends IDisposable {
     readonly model: IDiffEditorModel;
     waitForDiff(): Promise<void>;
 }
+/**
+ * An event describing that an editor has had its model reset (i.e. `editor.setModel()`).
+ */
 export interface IModelChangedEvent {
+    /**
+     * The `uri` of the previous model or null.
+     */
     readonly oldModelUrl: URI | null;
+    /**
+     * The `uri` of the new model or null.
+     */
     readonly newModelUrl: URI | null;
 }
 export interface IScrollEvent {
@@ -53,6 +123,9 @@ export interface IContentSizeChangedEvent {
     readonly contentWidthChanged: boolean;
     readonly contentHeightChanged: boolean;
 }
+/**
+ * @internal
+ */
 export interface ITriggerEditorOperationEvent {
     source: string | null | undefined;
     handlerId: string;
@@ -71,18 +144,29 @@ export interface IEditorAction {
     run(args?: unknown): Promise<void>;
 }
 export type IEditorModel = ITextModel | IDiffEditorModel | IDiffEditorViewModel;
+/**
+ * A (serializable) state of the cursors.
+ */
 export interface ICursorState {
     inSelectionMode: boolean;
     selectionStart: IPosition;
     position: IPosition;
 }
+/**
+ * A (serializable) state of the view.
+ */
 export interface IViewState {
+    /** written by previous versions */
     scrollTop?: number;
+    /** written by previous versions */
     scrollTopWithoutViewZones?: number;
     scrollLeft: number;
     firstPosition: IPosition;
     firstPositionDeltaTop: number;
 }
+/**
+ * A (serializable) state of the code editor.
+ */
 export interface ICodeEditorViewState {
     cursorState: ICursorState[];
     viewState: IViewState;
@@ -90,45 +174,130 @@ export interface ICodeEditorViewState {
         [id: string]: any;
     };
 }
+/**
+ * (Serializable) View state for the diff editor.
+ */
 export interface IDiffEditorViewState {
     original: ICodeEditorViewState | null;
     modified: ICodeEditorViewState | null;
     modelState?: unknown;
 }
+/**
+ * An editor view state.
+ */
 export type IEditorViewState = ICodeEditorViewState | IDiffEditorViewState;
 export declare enum ScrollType {
     Smooth = 0,
     Immediate = 1
 }
+/**
+ * An editor.
+ */
 export type IEditor = import("monaco-editor").editor.IEditor;
+/**
+ * A diff editor.
+ *
+ * @internal
+ */
 export interface IDiffEditor extends IEditor {
+    /**
+     * Type the getModel() of IEditor.
+     */
     getModel(): IDiffEditorModel | null;
+    /**
+     * Get the `original` editor.
+     */
     getOriginalEditor(): IEditor;
+    /**
+     * Get the `modified` editor.
+     */
     getModifiedEditor(): IEditor;
 }
+/**
+ * @internal
+ */
 export interface ICompositeCodeEditor {
+    /**
+     * An event that signals that the active editor has changed
+     */
     readonly onDidChangeActiveEditor: Event<ICompositeCodeEditor>;
+    /**
+     * The active code editor iff any
+     */
     readonly activeCodeEditor: IEditor | undefined;
 }
+/**
+ * A collection of decorations
+ */
 export interface IEditorDecorationsCollection {
+    /**
+     * An event emitted when decorations change in the editor,
+     * but the change is not caused by us setting or clearing the collection.
+     */
     onDidChange: Event<IModelDecorationsChangedEvent>;
+    /**
+     * Get the decorations count.
+     */
     length: number;
+    /**
+     * Get the range for a decoration.
+     */
     getRange(index: number): Range | null;
+    /**
+     * Get all ranges for decorations.
+     */
     getRanges(): Range[];
+    /**
+     * Determine if a decoration is in this collection.
+     */
     has(decoration: IModelDecoration): boolean;
+    /**
+     * Replace all previous decorations with `newDecorations`.
+     */
     set(newDecorations: readonly IModelDeltaDecoration[]): string[];
+    /**
+     * Append `newDecorations` to this collection.
+     */
     append(newDecorations: readonly IModelDeltaDecoration[]): string[];
+    /**
+     * Remove all previous decorations.
+     */
     clear(): void;
 }
+/**
+ * An editor contribution that gets created every time a new editor gets created and gets disposed when the editor gets disposed.
+ */
 export interface IEditorContribution {
+    /**
+     * Dispose this contribution.
+     */
     dispose(): void;
+    /**
+     * Store view state.
+     */
     saveViewState?(): any;
+    /**
+     * Restore view state.
+     */
     restoreViewState?(state: any): void;
 }
+/**
+ * A diff editor contribution that gets created every time a new  diffeditor gets created and gets disposed when the diff editor gets disposed.
+ * @internal
+ */
 export interface IDiffEditorContribution {
+    /**
+     * Dispose this contribution.
+     */
     dispose(): void;
 }
+/**
+ * @internal
+ */
 export declare function isThemeColor(o: any): o is ThemeColor;
+/**
+ * @internal
+ */
 export interface IThemeDecorationRenderOptions {
     backgroundColor?: string | ThemeColor;
     outline?: string;
@@ -154,15 +323,30 @@ export interface IThemeDecorationRenderOptions {
     gutterIconPath?: UriComponents;
     gutterIconSize?: string;
     overviewRulerColor?: string | ThemeColor;
+    /**
+     * @deprecated
+     */
     before?: IContentDecorationRenderOptions;
+    /**
+     * @deprecated
+     */
     after?: IContentDecorationRenderOptions;
+    /**
+     * @deprecated
+     */
     beforeInjectedText?: IContentDecorationRenderOptions & {
         affectsLetterSpacing?: boolean;
     };
+    /**
+     * @deprecated
+     */
     afterInjectedText?: IContentDecorationRenderOptions & {
         affectsLetterSpacing?: boolean;
     };
 }
+/**
+ * @internal
+ */
 export interface IContentDecorationRenderOptions {
     contentText?: string;
     contentIconPath?: UriComponents;
@@ -183,6 +367,9 @@ export interface IContentDecorationRenderOptions {
     width?: string;
     height?: string;
 }
+/**
+ * @internal
+ */
 export interface IDecorationRenderOptions extends IThemeDecorationRenderOptions {
     isWholeLine?: boolean;
     rangeBehavior?: TrackedRangeStickiness;
@@ -190,23 +377,45 @@ export interface IDecorationRenderOptions extends IThemeDecorationRenderOptions
     light?: IThemeDecorationRenderOptions;
     dark?: IThemeDecorationRenderOptions;
 }
+/**
+ * @internal
+ */
 export interface IThemeDecorationInstanceRenderOptions {
+    /**
+     * @deprecated
+     */
     before?: IContentDecorationRenderOptions;
+    /**
+     * @deprecated
+     */
     after?: IContentDecorationRenderOptions;
 }
+/**
+ * @internal
+ */
 export interface IDecorationInstanceRenderOptions extends IThemeDecorationInstanceRenderOptions {
     light?: IThemeDecorationInstanceRenderOptions;
     dark?: IThemeDecorationInstanceRenderOptions;
 }
+/**
+ * @internal
+ */
 export interface IDecorationOptions {
     range: IRange;
     hoverMessage?: IMarkdownString | IMarkdownString[];
     renderOptions?: IDecorationInstanceRenderOptions;
 }
+/**
+ * The type of the `IEditor`.
+ */
 export declare const EditorType: {
     ICodeEditor: string;
     IDiffEditor: string;
 };
+/**
+ * Built-in commands.
+ * @internal
+ */
 export declare enum Handler {
     CompositionStart = "compositionStart",
     CompositionEnd = "compositionEnd",
@@ -216,13 +425,22 @@ export declare enum Handler {
     Paste = "paste",
     Cut = "cut"
 }
+/**
+ * @internal
+ */
 export interface TypePayload {
     text: string;
 }
+/**
+ * @internal
+ */
 export interface ReplacePreviousCharPayload {
     text: string;
     replaceCharCnt: number;
 }
+/**
+ * @internal
+ */
 export interface CompositionTypePayload {
     text: string;
     replacePrevCharCnt: number;

package/vscode/src/vs/editor/common/editorContextKeys.d.ts

@@ -1,8 +1,18 @@
 import { RawContextKey } from "../../platform/contextkey/common/contextkey.js";
 export declare namespace EditorContextKeys {
     const editorSimpleInput: RawContextKey<boolean>;
+    /**
+     * A context key that is set when the editor's text has focus (cursor is blinking).
+     * Is false when focus is in simple editor widgets (repl input, scm commit input).
+     */
     const editorTextFocus: RawContextKey<boolean>;
+    /**
+     * A context key that is set when the editor's text or an editor's widget has focus.
+     */
     const focus: RawContextKey<boolean>;
+    /**
+     * A context key that is set when any editor input has focus (regular editor, repl input...).
+     */
     const textInputFocus: RawContextKey<boolean>;
     const readOnly: RawContextKey<boolean>;
     const inDiffEditor: RawContextKey<boolean>;
@@ -34,6 +44,10 @@ export declare namespace EditorContextKeys {
     const stickyScrollVisible: RawContextKey<boolean>;
     const standaloneColorPickerVisible: RawContextKey<boolean>;
     const standaloneColorPickerFocused: RawContextKey<boolean>;
+    /**
+     * A context key that is set when an editor is part of a larger editor, like notebooks or
+     * (future) a diff editor
+     */
     const inCompositeEditor: RawContextKey<boolean>;
     const notInCompositeEditor: import("../../platform/contextkey/common/contextkey.js").ContextKeyExpression;
     const languageId: RawContextKey<string>;

package/vscode/src/vs/editor/common/editorFeatures.d.ts

@@ -1,7 +1,14 @@
 import { BrandedService, IConstructorSignature } from "../../platform/instantiation/common/instantiation.js";
+/**
+ * A feature that will be loaded when the first code editor is constructed and disposed when the system shuts down.
+ */
 export interface IEditorFeature {
 }
 export type EditorFeatureCtor = IConstructorSignature<IEditorFeature>;
+/**
+ * Registers an editor feature. Editor features will be instantiated only once, as soon as
+ * the first code editor is instantiated.
+ */
 export declare function registerEditorFeature<Services extends BrandedService[]>(ctor: {
     new (...services: Services): IEditorFeature;
 }): void;

package/vscode/src/vs/editor/common/encodedTokenAttributes.d.ts

@@ -1,7 +1,13 @@
+/**
+ * Open ended enum at runtime
+ */
 export declare enum LanguageId {
     Null = 0,
     PlainText = 1
 }
+/**
+ * A font style. Values are 2^x such that a bit mask can be used.
+ */
 export declare enum FontStyle {
     NotSet = -1,
     None = 0,
@@ -10,17 +16,45 @@ export declare enum FontStyle {
     Underline = 4,
     Strikethrough = 8
 }
+/**
+ * Open ended enum at runtime
+ */
 export declare enum ColorId {
     None = 0,
     DefaultForeground = 1,
     DefaultBackground = 2
 }
+/**
+ * A standard token type.
+ */
 export declare enum StandardTokenType {
     Other = 0,
     Comment = 1,
     String = 2,
     RegEx = 3
 }
+/**
+ * Helpers to manage the "collapsed" metadata of an entire StackElement stack.
+ * The following assumptions have been made:
+ *  - languageId < 256 => needs 8 bits
+ *  - unique color count < 512 => needs 9 bits
+ *
+ * The binary format is:
+ * - -------------------------------------------
+ *     3322 2222 2222 1111 1111 1100 0000 0000
+ *     1098 7654 3210 9876 5432 1098 7654 3210
+ * - -------------------------------------------
+ *     xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
+ *     bbbb bbbb ffff ffff fFFF FBTT LLLL LLLL
+ * - -------------------------------------------
+ *  - L = LanguageId (8 bits)
+ *  - T = StandardTokenType (2 bits)
+ *  - B = Balanced bracket (1 bit)
+ *  - F = FontStyle (4 bits)
+ *  - f = foreground color (9 bits)
+ *  - b = background color (8 bits)
+ *
+ */
 export declare enum MetadataConsts {
     LANGUAGEID_MASK = 255,
     TOKEN_TYPE_MASK = 768,
@@ -45,6 +79,8 @@ export declare enum MetadataConsts {
     FOREGROUND_OFFSET = 15,
     BACKGROUND_OFFSET = 24
 }
+/**
+ */
 export declare class TokenMetadata {
     static getLanguageId(metadata: number): LanguageId;
     static getTokenType(metadata: number): StandardTokenType;
@@ -56,6 +92,8 @@ export declare class TokenMetadata {
     static getInlineStyleFromMetadata(metadata: number, colorMap: string[]): string;
     static getPresentationFromMetadata(metadata: number): ITokenPresentation;
 }
+/**
+ */
 export interface ITokenPresentation {
     foreground: ColorId;
     italic: boolean;

package/vscode/src/vs/editor/common/inputMode.d.ts

@@ -6,5 +6,8 @@ declare class InputModeImpl {
     getInputMode(): "overtype" | "insert";
     setInputMode(inputMode: "overtype" | "insert"): void;
 }
+/**
+ * Controls the type mode, whether insert or overtype
+ */
 export declare const InputMode: InputModeImpl;
 export {};

package/vscode/src/vs/editor/common/languageSelector.d.ts

@@ -5,8 +5,14 @@ export interface LanguageFilter {
     readonly scheme?: string;
     readonly pattern?: string | IRelativePattern;
     readonly notebookType?: string;
+    /**
+     * This provider is implemented in the UI thread.
+     */
     readonly hasAccessToAllModels?: boolean;
     readonly exclusive?: boolean;
+    /**
+     * This provider comes from a builtin extension.
+     */
     readonly isBuiltin?: boolean;
 }
 export type LanguageSelector = string | LanguageFilter | ReadonlyArray<string | LanguageFilter>;

package/vscode/src/vs/editor/common/languages/autoIndent.d.ts

@@ -19,6 +19,18 @@ export interface IIndentConverter {
     unshiftIndent(indentation: string): string;
     normalizeIndentation?(indentation: string): string;
 }
+/**
+ * Get inherited indentation from above lines.
+ * 1. Find the nearest preceding line which doesn't match unIndentedLinePattern.
+ * 2. If this line matches indentNextLinePattern or increaseIndentPattern, it means that the indent level of `lineNumber` should be 1 greater than this line.
+ * 3. If this line doesn't match any indent rules
+ *   a. check whether the line above it matches indentNextLinePattern
+ *   b. If not, the indent level of this line is the result
+ *   c. If so, it means the indent of this line is *temporary*, go upward utill we find a line whose indent is not temporary (the same workflow a -> b -> c).
+ * 4. Otherwise, we fail to get an inherited indent from aboves. Return null and we should not touch the indent of `lineNumber`
+ *
+ * This function only return the inherited indent based on above lines, it doesn't check whether current line should decrease or not.
+ */
 export declare function getInheritIndentForLine(autoIndent: EditorAutoIndentStrategy, model: IVirtualModel, lineNumber: number, honorIntentialIndent: boolean | undefined, languageConfigurationService: ILanguageConfigurationService): {
     indentation: string;
     action: IndentAction | null;
@@ -29,5 +41,9 @@ export declare function getIndentForEnter(autoIndent: EditorAutoIndentStrategy,
     beforeEnter: string;
     afterEnter: string;
 } | null;
+/**
+ * We should always allow intentional indentation. It means, if users change the indentation of `lineNumber` and the content of
+ * this line doesn't match decreaseIndentPattern, we should not adjust the indentation.
+ */
 export declare function getIndentActionForType(cursorConfig: CursorConfiguration, model: ITextModel, range: Range, ch: string, indentConverter: IIndentConverter, languageConfigurationService: ILanguageConfigurationService): string | null;
 export declare function getIndentMetadata(model: ITextModel, lineNumber: number, languageConfigurationService: ILanguageConfigurationService): number | null;

package/vscode/src/vs/editor/common/languages/defaultDocumentColorsComputer.d.ts

@@ -5,4 +5,7 @@ export interface IDocumentColorComputerTarget {
     positionAt(offset: number): IPosition;
     findMatches(regex: RegExp): RegExpMatchArray[];
 }
+/**
+ * Returns an array of all default document colors in the provided document
+ */
 export declare function computeDefaultDocumentColors(model: IDocumentColorComputerTarget): IColorInformation[];

package/vscode/src/vs/editor/common/languages/language.d.ts

@@ -9,6 +9,9 @@ export interface ILanguageExtensionPoint {
     aliases?: string[];
     mimetypes?: string[];
     configuration?: URI;
+    /**
+     * @internal
+     */
     icon?: ILanguageIcon;
 }
 export interface ILanguageSelection {

package/vscode/src/vs/editor/common/languages/language.service.d.ts

@@ -6,26 +6,103 @@ import { ILanguageExtensionPoint, ILanguageNameIdPair, ILanguageIcon, ILanguageS
 export declare const ILanguageService: import("../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<ILanguageService>;
 export interface ILanguageService {
     readonly _serviceBrand: undefined;
+    /**
+    * A codec which can encode and decode a string `languageId` as a number.
+    */
     readonly languageIdCodec: ILanguageIdCodec;
+    /**
+    * An event emitted when basic language features are requested for the first time.
+    * This event is emitted when embedded languages are encountered (e.g. JS code block inside Markdown)
+    * or when a language is associated to a text model.
+    *
+    * **Note**: Basic language features refers to language configuration related features.
+    * **Note**: This event is a superset of `onDidRequestRichLanguageFeatures`
+    */
     onDidRequestBasicLanguageFeatures: Event<string>;
+    /**
+    * An event emitted when rich language features are requested for the first time.
+    * This event is emitted when a language is associated to a text model.
+    *
+    * **Note**: Rich language features refers to tokenizers, language features based on providers, etc.
+    * **Note**: This event is a subset of `onDidRequestRichLanguageFeatures`
+    */
     onDidRequestRichLanguageFeatures: Event<string>;
+    /**
+    * An event emitted when languages have changed.
+    */
     onDidChange: Event<void>;
+    /**
+    * Register a language.
+    */
     registerLanguage(def: ILanguageExtensionPoint): IDisposable;
+    /**
+    * Check if `languageId` is registered.
+    */
     isRegisteredLanguageId(languageId: string): boolean;
+    /**
+    * Get a list of all registered languages.
+    */
     getRegisteredLanguageIds(): string[];
+    /**
+    * Get a list of all registered languages with a name.
+    * If a language is explicitly registered without a name, it will not be part of the result.
+    * The result is sorted using by name case insensitive.
+    */
     getSortedRegisteredLanguageNames(): ILanguageNameIdPair[];
+    /**
+    * Get the preferred language name for a language.
+    */
     getLanguageName(languageId: string): string | null;
+    /**
+    * Get the mimetype for a language.
+    */
     getMimeType(languageId: string): string | null;
+    /**
+    * Get the default icon for the language.
+    */
     getIcon(languageId: string): ILanguageIcon | null;
+    /**
+    * Get all file extensions for a language.
+    */
     getExtensions(languageId: string): ReadonlyArray<string>;
+    /**
+    * Get all file names for a language.
+    */
     getFilenames(languageId: string): ReadonlyArray<string>;
+    /**
+    * Get all language configuration files for a language.
+    */
     getConfigurationFiles(languageId: string): ReadonlyArray<URI>;
+    /**
+    * Look up a language by its name case insensitive.
+    */
     getLanguageIdByLanguageName(languageName: string): string | null;
+    /**
+    * Look up a language by its mime type.
+    */
     getLanguageIdByMimeType(mimeType: string | null | undefined): string | null;
+    /**
+    * Guess the language id for a resource.
+    */
     guessLanguageIdByFilepathOrFirstLine(resource: URI, firstLine?: string): string | null;
+    /**
+    * Will fall back to 'plaintext' if `languageId` is unknown.
+    */
     createById(languageId: string | null | undefined): ILanguageSelection;
+    /**
+    * Will fall back to 'plaintext' if `mimeType` is unknown.
+    */
     createByMimeType(mimeType: string | null | undefined): ILanguageSelection;
+    /**
+    * Will fall back to 'plaintext' if the `languageId` cannot be determined.
+    */
     createByFilepathOrFirstLine(resource: URI | null, firstLine?: string): ILanguageSelection;
+    /**
+    * Request basic language features for a language.
+    */
     requestBasicLanguageFeatures(languageId: string): void;
+    /**
+    * Request rich language features for a language.
+    */
     requestRichLanguageFeatures(languageId: string): void;
 }