@codingame/monaco-vscode-api 20.1.1 → 20.2.1

package/vscode/src/vs/platform/theme/common/colorUtils.d.ts

@@ -10,6 +10,12 @@ export interface ColorContribution {
     readonly needsTransparency: boolean;
     readonly deprecationMessage: string | undefined;
 }
+/**
+ * Returns the css variable name for the given color identifier. Dots (`.`) are replaced with hyphens (`-`) and
+ * everything is prefixed with `--vscode-`.
+ *
+ * @sample `editorSuggestWidget.background` is `--vscode-editorSuggestWidget-background`.
+ */
 export declare function asCssVariableName(colorIdent: ColorIdentifier): string;
 export declare function asCssVariable(color: ColorIdentifier): string;
 export declare function asCssVariableWithDefault(color: ColorIdentifier, defaultCssValue: string): string;
@@ -66,6 +72,9 @@ export interface ColorDefaults {
     hcLight: ColorValue | null;
 }
 export declare function isColorDefaults(value: unknown): value is ColorDefaults;
+/**
+ * A Color Value is either a color literal, a reference to an other color or a derived color
+ */
 export type ColorValue = Color | string | ColorIdentifier | ColorTransform;
 export declare const Extensions: {
     ColorContribution: string;
@@ -73,12 +82,37 @@ export declare const Extensions: {
 export declare const DEFAULT_COLOR_CONFIG_VALUE = "default";
 export interface IColorRegistry {
     readonly onDidChangeSchema: Event<void>;
+    /**
+     * Register a color to the registry.
+     * @param id The color id as used in theme description files
+     * @param defaults The default values
+     * @param needsTransparency Whether the color requires transparency
+     * @description the description
+     */
     registerColor(id: string, defaults: ColorDefaults, description: string, needsTransparency?: boolean): ColorIdentifier;
+    /**
+     * Register a color to the registry.
+     */
     deregisterColor(id: string): void;
+    /**
+     * Get all color contributions
+     */
     getColors(): ColorContribution[];
+    /**
+     * Gets the default color of the given id
+     */
     resolveDefaultColor(id: ColorIdentifier, theme: IColorTheme): Color | undefined;
+    /**
+     * JSON schema for an object to assign color values to one of the color contributions.
+     */
     getColorSchema(): IJSONSchema;
+    /**
+     * JSON schema to for a reference to a color contribution.
+     */
     getColorReferenceSchema(): IJSONSchema;
+    /**
+     * Notify when the color theme or settings change.
+     */
     notifyThemeUpdate(theme: IColorTheme): void;
 }
 export declare function registerColor(id: string, defaults: ColorDefaults | ColorValue | null, description: string, needsTransparency?: boolean, deprecationMessage?: string): ColorIdentifier;
@@ -91,5 +125,8 @@ export declare function opaque(colorValue: ColorValue, background: ColorValue):
 export declare function oneOf(...colorValues: ColorValue[]): ColorTransform;
 export declare function ifDefinedThenElse(ifArg: ColorIdentifier, thenArg: ColorValue, elseArg: ColorValue): ColorTransform;
 export declare function lessProminent(colorValue: ColorValue, backgroundColorValue: ColorValue, factor: number, transparency: number): ColorTransform;
+/**
+ * @param colorValue Resolve a color value in the context of a theme
+ */
 export declare function resolveColorValue(colorValue: ColorValue | null, theme: IColorTheme): Color | undefined;
 export declare const workbenchColorsSchemaId = "vscode://schemas/workbench-colors";

package/vscode/src/vs/platform/theme/common/iconRegistry.d.ts

@@ -38,14 +38,46 @@ export interface IconFontSource {
 }
 export interface IIconRegistry {
     readonly onDidChange: Event<void>;
+    /**
+     * Register a icon to the registry.
+     * @param id The icon id
+     * @param defaults The default values
+     * @param description The description
+     */
     registerIcon(id: IconIdentifier, defaults: IconDefaults, description?: string): ThemeIcon;
+    /**
+     * Deregister a icon from the registry.
+     */
     deregisterIcon(id: IconIdentifier): void;
+    /**
+     * Get all icon contributions
+     */
     getIcons(): IconContribution[];
+    /**
+     * Get the icon for the given id
+     */
     getIcon(id: IconIdentifier): IconContribution | undefined;
+    /**
+     * JSON schema for an object to assign icon values to one of the icon contributions.
+     */
     getIconSchema(): IJSONSchema;
+    /**
+     * JSON schema to for a reference to a icon contribution.
+     */
     getIconReferenceSchema(): IJSONSchema;
+    /**
+     * Register a icon font to the registry.
+     * @param id The icon font id
+     * @param definition The icon font definition
+     */
     registerIconFont(id: string, definition: IconFontDefinition): IconFontDefinition;
+    /**
+     * Deregister an icon font to the registry.
+     */
     deregisterIconFont(id: string): void;
+    /**
+     * Get the icon font for the given id
+     */
     getIconFont(id: string): IconFontDefinition | undefined;
 }
 export declare const fontIdRegex: RegExp;

package/vscode/src/vs/platform/theme/common/theme.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Color scheme used by the OS and by color themes.
+ */
 export declare enum ColorScheme {
     DARK = "dark",
     LIGHT = "light",

package/vscode/src/vs/platform/theme/common/themeService.d.ts

@@ -22,10 +22,29 @@ export interface ITokenStyle {
 export interface IColorTheme {
     readonly type: ColorScheme;
     readonly label: string;
+    /**
+     * Resolves the color of the given color identifier. If the theme does not
+     * specify the color, the default color is returned unless <code>useDefault</code> is set to false.
+     * @param color the id of the color
+     * @param useDefault specifies if the default color should be used. If not set, the default is used.
+     */
     getColor(color: ColorIdentifier, useDefault?: boolean): Color | undefined;
+    /**
+     * Returns whether the theme defines a value for the color. If not, that means the
+     * default color will be used.
+     */
     defines(color: ColorIdentifier): boolean;
+    /**
+     * Returns the token style for a given classification. The result uses the <code>MetadataConsts</code> format
+     */
     getTokenStyleMetadata(type: string, modifiers: string[], modelLanguage: string): ITokenStyle | undefined;
+    /**
+     * List of all colors used with tokens. <code>getTokenStyleMetadata</code> references the colors by index into this list.
+     */
     readonly tokenColorMap: string[];
+    /**
+     * Defines whether semantic highlighting should be enabled for the theme.
+     */
     readonly semanticHighlighting: boolean;
 }
 export interface IFileIconTheme {
@@ -34,6 +53,11 @@ export interface IFileIconTheme {
     readonly hidesExplorerArrows: boolean;
 }
 export interface IProductIconTheme {
+    /**
+     * Resolves the definition for the given icon as defined by the theme.
+     *
+     * @param iconContribution The icon
+     */
     getIcon(iconContribution: IconContribution): IconDefinition | undefined;
 }
 export interface ICssStyleCollector {
@@ -46,11 +70,17 @@ export declare const Extensions: {
     ThemingContribution: string;
 };
 export interface IThemingRegistry {
+    /**
+     * Register a theming participant that is invoked on every theme change.
+     */
     onColorThemeChange(participant: IThemingParticipant): IDisposable;
     getThemingParticipants(): IThemingParticipant[];
     readonly onThemingParticipantAdded: Event<IThemingParticipant>;
 }
 export declare function registerThemingParticipant(participant: IThemingParticipant): IDisposable;
+/**
+ * Utility base class for all themable components.
+ */
 export declare class Themable extends Disposable {
     protected themeService: IThemeService;
     protected theme: IColorTheme;

package/vscode/src/vs/platform/tunnel/common/tunnel.d.ts

@@ -33,7 +33,7 @@ export declare enum TunnelProtocol {
     Https = "https"
 }
 export declare enum TunnelPrivacyId {
-    ConstantPrivate = "constantPrivate",
+    ConstantPrivate = "constantPrivate",// private, and changing is unsupported
     Private = "private",
     Public = "public"
 }
@@ -42,6 +42,9 @@ export interface TunnelCreationOptions {
 }
 export interface TunnelProviderFeatures {
     elevation: boolean;
+    /**
+     * @deprecated
+     */
     public?: boolean;
     privacyOptions: TunnelPrivacy[];
     protocol: boolean;
@@ -70,10 +73,19 @@ export interface ITunnel {
         port: number;
         host: string;
     };
+    /**
+     * The complete local address(ex. localhost:1234)
+     */
     localAddress: string;
+    /**
+     * @deprecated Use privacy instead
+     */
     public?: boolean;
     privacy?: string;
     protocol?: string;
+    /**
+     * Implementers of Tunnel should fire onDidDispose when dispose is called.
+     */
     onDidDispose: Event<void>;
     dispose(): Promise<void> | void;
 }

package/vscode/src/vs/platform/undoRedo/common/undoRedo.d.ts

@@ -6,22 +6,54 @@ export declare enum UndoRedoElementType {
 }
 export interface IResourceUndoRedoElement {
     readonly type: UndoRedoElementType.Resource;
+    /**
+     * The resource impacted by this element.
+     */
     readonly resource: URI;
+    /**
+     * A user presentable label. May be localized.
+     */
     readonly label: string;
+    /**
+     * A code describing the operation. Will not be localized.
+     */
     readonly code: string;
+    /**
+     * Show a message to the user confirming when trying to undo this element
+     */
     readonly confirmBeforeUndo?: boolean;
     undo(): Promise<void> | void;
     redo(): Promise<void> | void;
 }
 export interface IWorkspaceUndoRedoElement {
     readonly type: UndoRedoElementType.Workspace;
+    /**
+     * The resources impacted by this element.
+     */
     readonly resources: readonly URI[];
+    /**
+     * A user presentable label. May be localized.
+     */
     readonly label: string;
+    /**
+     * A code describing the operation. Will not be localized.
+     */
     readonly code: string;
+    /**
+     * Show a message to the user confirming when trying to undo this element
+     */
     readonly confirmBeforeUndo?: boolean;
     undo(): Promise<void> | void;
     redo(): Promise<void> | void;
+    /**
+     * If implemented, indicates that this undo/redo element can be split into multiple per resource elements.
+     */
     split?(): IResourceUndoRedoElement[];
+    /**
+     * If implemented, will be invoked before calling `undo()` or `redo()`.
+     * This is a good place to prepare everything such that the calls to `undo()` or `redo()` are synchronous.
+     * If a disposable is returned, it will be invoked to clean things up.
+     */
     prepareUndoRedo?(): Promise<IDisposable> | IDisposable | void;
 }
 export type IUndoRedoElement = IResourceUndoRedoElement | IWorkspaceUndoRedoElement;

package/vscode/src/vs/platform/undoRedo/common/undoRedo.service.d.ts

@@ -4,14 +4,46 @@ import { UriComparisonKeyComputer, IUndoRedoElement, UndoRedoGroup, UndoRedoSour
 export declare const IUndoRedoService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IUndoRedoService>;
 export interface IUndoRedoService {
     readonly _serviceBrand: undefined;
+    /**
+    * Register an URI -> string hasher.
+    * This is useful for making multiple URIs share the same undo-redo stack.
+    */
     registerUriComparisonKeyComputer(scheme: string, uriComparisonKeyComputer: UriComparisonKeyComputer): IDisposable;
+    /**
+    * Get the hash used internally for a certain URI.
+    * This uses any registered `UriComparisonKeyComputer`.
+    */
     getUriComparisonKey(resource: URI): string;
+    /**
+    * Add a new element to the `undo` stack.
+    * This will destroy the `redo` stack.
+    */
     pushElement(element: IUndoRedoElement, group?: UndoRedoGroup, source?: UndoRedoSource): void;
+    /**
+    * Get the last pushed element for a resource.
+    * If the last pushed element has been undone, returns null.
+    */
     getLastElement(resource: URI): IUndoRedoElement | null;
+    /**
+    * Get all the elements associated with a resource.
+    * This includes the past and the future.
+    */
     getElements(resource: URI): IPastFutureElements;
+    /**
+    * Validate or invalidate stack elements associated with a resource.
+    */
     setElementsValidFlag(resource: URI, isValid: boolean, filter: (element: IUndoRedoElement) => boolean): void;
+    /**
+    * Remove elements that target `resource`.
+    */
     removeElements(resource: URI): void;
+    /**
+    * Create a snapshot of the current elements on the undo-redo stack for a resource.
+    */
     createSnapshot(resource: URI): ResourceEditStackSnapshot;
+    /**
+    * Attempt (as best as possible) to restore a certain snapshot previously created with `createSnapshot` for a resource.
+    */
     restoreSnapshot(snapshot: ResourceEditStackSnapshot): void;
     canUndo(resource: URI | UndoRedoSource): boolean;
     undo(resource: URI | UndoRedoSource): Promise<void> | void;

package/vscode/src/vs/platform/update/common/update.d.ts

@@ -6,6 +6,23 @@ export interface IUpdate {
     url?: string;
     sha256hash?: string;
 }
+/**
+ * Updates are run as a state machine:
+ *
+ *      Uninitialized
+ *           ↓
+ *          Idle
+ *          ↓  ↑
+ *   Checking for Updates  →  Available for Download
+ *         ↓
+ *     Downloading  →   Ready
+ *         ↓               ↑
+ *     Downloaded   →  Updating
+ *
+ * Available: There is an update available for download (linux).
+ * Ready: Code will be updated as soon as it restarts (win32, darwin).
+ * Downloaded: There is an update ready to be installed in the background (win32).
+ */
 export declare enum StateType {
     Uninitialized = "uninitialized",
     Idle = "idle",

package/vscode/src/vs/platform/uriIdentity/common/uriIdentity.service.d.ts

@@ -3,6 +3,32 @@ import { URI } from "../../../base/common/uri.js";
 export declare const IUriIdentityService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IUriIdentityService>;
 export interface IUriIdentityService {
     readonly _serviceBrand: undefined;
+    /**
+    * Uri extensions that are aware of casing.
+    */
     readonly extUri: IExtUri;
+    /**
+    * Returns a canonical uri for the given resource. Different uris can point to the same
+    * resource. That's because of casing or missing normalization, e.g the following uris
+    * are different but refer to the same document (because windows paths are not case-sensitive)
+    *
+    * ```txt
+    * file:///c:/foo/bar.txt
+    * file:///c:/FOO/BAR.txt
+    * ```
+    *
+    * This function should be invoked when feeding uris into the system that represent the truth,
+    * e.g document uris or marker-to-document associations etc. This function should NOT be called
+    * to pretty print a label nor to sanitize a uri.
+    *
+    * Samples:
+    *
+    * | in | out | |
+    * |---|---|---|
+    * | `file:///foo/bar/../bar` | `file:///foo/bar` | n/a |
+    * | `file:///foo/bar/../bar#frag` | `file:///foo/bar#frag` | keep fragment |
+    * | `file:///foo/BAR` | `file:///foo/bar` | assume ignore case |
+    * | `file:///foo/bar/../BAR?q=2` | `file:///foo/BAR?q=2` | query makes it a different document |
+    */
     asCanonicalUri(uri: URI): URI;
 }

package/vscode/src/vs/platform/url/common/url.d.ts

@@ -1,5 +1,11 @@
 import { URI } from "../../../base/common/uri.js";
 export interface IOpenURLOptions {
+    /**
+     * If not provided or `false`, signals that the
+     * URL to open did not originate from the product
+     * but outside. As such, a confirmation dialog
+     * might be shown to the user.
+     */
     trusted?: boolean;
     originalUrl?: string;
 }

package/vscode/src/vs/platform/url/common/url.service.d.ts

@@ -4,6 +4,11 @@ import { IOpenURLOptions, IURLHandler } from "./url.js";
 export declare const IURLService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IURLService>;
 export interface IURLService {
     readonly _serviceBrand: undefined;
+    /**
+    * Create a URL that can be called to trigger IURLhandlers.
+    * The URL that gets passed to the IURLHandlers carries over
+    * any of the provided IURLCreateOption values.
+    */
     create(options?: Partial<UriComponents>): URI;
     open(url: URI, options?: IOpenURLOptions): Promise<boolean>;
     registerHandler(handler: IURLHandler): IDisposable;

package/vscode/src/vs/platform/userDataProfile/common/userDataProfile.d.ts

@@ -18,6 +18,9 @@ export declare enum ProfileResourceType {
     GlobalState = "globalState",
     Mcp = "mcp"
 }
+/**
+ * Flags to indicate whether to use the default profile or not.
+ */
 export type UseDefaultProfileFlags = {
     [key in ProfileResourceType]?: boolean;
 };

package/vscode/src/vs/platform/userDataProfile/common/userDataProfileStorageService.service.d.ts

@@ -6,8 +6,24 @@ import { IProfileStorageChanges, IStorageValue } from "@codingame/monaco-vscode-
 export declare const IUserDataProfileStorageService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IUserDataProfileStorageService>;
 export interface IUserDataProfileStorageService {
     readonly _serviceBrand: undefined;
+    /**
+    * Emitted whenever data is updated or deleted in a profile storage or target of a profile storage entry changes
+    */
     readonly onDidChange: Event<IProfileStorageChanges>;
+    /**
+    * Return the requested profile storage data
+    * @param profile The profile from which the data has to be read from
+    */
     readStorageData(profile: IUserDataProfile): Promise<Map<string, IStorageValue>>;
+    /**
+    * Update the given profile storage data in the profile storage
+    * @param profile The profile to which the data has to be written to
+    * @param data Data that has to be updated
+    * @param target Storage target of the data
+    */
     updateStorageData(profile: IUserDataProfile, data: Map<string, string | undefined | null>, target: StorageTarget): Promise<void>;
+    /**
+    * Calls a function with a storage service scoped to given profile.
+    */
     withProfileScopedStorageService<T>(profile: IUserDataProfile, fn: (storageService: IStorageService) => Promise<T>): Promise<T>;
 }

package/vscode/src/vs/platform/userDataSync/common/userDataSync.d.ts

@@ -102,18 +102,18 @@ export declare const HEADER_OPERATION_ID = "x-operation-id";
 export declare const HEADER_EXECUTION_ID = "X-Execution-Id";
 export declare function createSyncHeaders(executionId: string): IHeaders;
 export declare enum UserDataSyncErrorCode {
-    Unauthorized = "Unauthorized",
-    Forbidden = "Forbidden",
-    NotFound = "NotFound",
-    MethodNotFound = "MethodNotFound",
-    Conflict = "Conflict",
-    Gone = "Gone",
-    PreconditionFailed = "PreconditionFailed",
-    TooLarge = "TooLarge",
-    UpgradeRequired = "UpgradeRequired",
-    PreconditionRequired = "PreconditionRequired",
-    TooManyRequests = "RemoteTooManyRequests",
-    TooManyRequestsAndRetryAfter = "TooManyRequestsAndRetryAfter",
+    Unauthorized = "Unauthorized",/* 401 */
+    Forbidden = "Forbidden",/* 403 */
+    NotFound = "NotFound",/* 404 */
+    MethodNotFound = "MethodNotFound",/* 405 */
+    Conflict = "Conflict",/* 409 */
+    Gone = "Gone",/* 410 */
+    PreconditionFailed = "PreconditionFailed",/* 412 */
+    TooLarge = "TooLarge",/* 413 */
+    UpgradeRequired = "UpgradeRequired",/* 426 */
+    PreconditionRequired = "PreconditionRequired",/* 428 */
+    TooManyRequests = "RemoteTooManyRequests",/* 429 */
+    TooManyRequestsAndRetryAfter = "TooManyRequestsAndRetryAfter",/* 429 + Retry-After */
     RequestFailed = "RequestFailed",
     RequestCanceled = "RequestCanceled",
     RequestTimeout = "RequestTimeout",

package/vscode/src/vs/platform/userDataSync/common/userDataSync.service.d.ts

@@ -57,6 +57,10 @@ export interface IUserDataSyncEnablementService {
     isResourceEnabled(resource: SyncResource, defaultValue?: boolean): boolean;
     setResourceEnablement(resource: SyncResource, enabled: boolean): void;
     getResourceSyncStateVersion(resource: SyncResource): string | undefined;
+    /**
+    * Checks if resource enabled was explicitly configured before,
+    * ignoring its default enablement value used in {@link isResourceEnabled}.
+    */
     isResourceEnablementConfigured(resource: SyncResource): boolean;
 }
 export declare const IUserDataSyncService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IUserDataSyncService>;

package/vscode/src/vs/platform/webContentExtractor/common/webContentExtractor.d.ts

@@ -2,6 +2,11 @@ import { VSBuffer } from "../../../base/common/buffer.js";
 import { CancellationToken } from "../../../base/common/cancellation.js";
 import { URI } from "../../../base/common/uri.js";
 import { IWebContentExtractorService, type ISharedWebContentExtractorService } from "./webContentExtractor.service.js";
+/**
+ * A service that extracts web content from a given URI.
+ * This is a placeholder implementation that does not perform any actual extraction.
+ * It's intended to be used on platforms where web content extraction is not supported such as in the browser.
+ */
 export declare class NullWebContentExtractorService implements IWebContentExtractorService {
     _serviceBrand: undefined;
     extract(_uri: URI[]): Promise<string[]>;

package/vscode/src/vs/platform/window/common/window.d.ts

@@ -26,7 +26,17 @@ export interface IRectangle extends IPoint {
     readonly height: number;
 }
 export interface IBaseOpenWindowsOptions {
+    /**
+     * Whether to reuse the window or open a new one.
+     */
     readonly forceReuseWindow?: boolean;
+    /**
+     * The remote authority to use when windows are opened with either
+     * - no workspace (empty window)
+     * - a workspace that is neither `file://` nor `vscode-remote://`
+     * Use 'null' for a local window.
+     * If not set, defaults to the remote authority of the current window.
+     */
     readonly remoteAuthority?: string | null;
     readonly forceProfile?: string;
     readonly forceTempProfile?: boolean;
@@ -145,13 +155,35 @@ export declare const DEFAULT_CUSTOM_TITLEBAR_HEIGHT = 35;
 export declare function useWindowControlsOverlay(configurationService: IConfigurationService): boolean;
 export declare function useNativeFullScreen(configurationService: IConfigurationService): boolean;
 export interface IPath<T = IEditorOptions> extends IPathData<T> {
+    /**
+     * The file path to open within the instance
+     */
     fileUri?: URI;
 }
 export interface IPathData<T = IEditorOptions> {
+    /**
+     * The file path to open within the instance
+     */
     readonly fileUri?: UriComponents;
+    /**
+     * Optional editor options to apply in the file
+     */
     readonly options?: T;
+    /**
+     * A hint that the file exists. if true, the
+     * file exists, if false it does not. with
+     * `undefined` the state is unknown.
+     */
     readonly exists?: boolean;
+    /**
+     * A hint about the file type of this path.
+     * with `undefined` the type is unknown.
+     */
     readonly type?: FileType;
+    /**
+     * Specifies if the file should be only be opened
+     * if it exists.
+     */
     readonly openOnlyIfExists?: boolean;
 }
 export interface IPathsToWaitFor extends IPathsToWaitForData {
@@ -167,6 +199,9 @@ export interface IOpenFileRequest {
     readonly filesToDiff?: IPathData[];
     readonly filesToMerge?: IPathData[];
 }
+/**
+ * Additional context for the request on native only.
+ */
 export interface INativeOpenFileRequest extends IOpenFileRequest {
     readonly termProgram?: string;
     readonly filesToWait?: IPathsToWaitForData;
@@ -230,6 +265,10 @@ export interface INativeWindowConfiguration extends IWindowConfiguration, Native
         value: PolicyValue;
     }>;
 }
+/**
+ * According to Electron docs: `scale := 1.2 ^ level`.
+ * https://github.com/electron/electron/blob/master/docs/api/web-contents.md#contentssetzoomlevellevel
+ */
 export declare function zoomLevelToZoomFactor(zoomLevel?: number): number;
 export declare const DEFAULT_WINDOW_SIZE: {
     readonly width: 1200;