@codingame/monaco-vscode-api 20.1.1 → 20.2.1

package/vscode/src/vs/base/common/color.d.ts

@@ -1,29 +1,77 @@
 export declare class RGBA {
     _rgbaBrand: void;
+    /**
+     * Red: integer in [0-255]
+     */
     readonly r: number;
+    /**
+     * Green: integer in [0-255]
+     */
     readonly g: number;
+    /**
+     * Blue: integer in [0-255]
+     */
     readonly b: number;
+    /**
+     * Alpha: float in [0-1]
+     */
     readonly a: number;
     constructor(r: number, g: number, b: number, a?: number);
     static equals(a: RGBA, b: RGBA): boolean;
 }
 export declare class HSLA {
     _hslaBrand: void;
+    /**
+     * Hue: integer in [0, 360]
+     */
     readonly h: number;
+    /**
+     * Saturation: float in [0, 1]
+     */
     readonly s: number;
+    /**
+     * Luminosity: float in [0, 1]
+     */
     readonly l: number;
+    /**
+     * Alpha: float in [0, 1]
+     */
     readonly a: number;
     constructor(h: number, s: number, l: number, a: number);
     static equals(a: HSLA, b: HSLA): boolean;
+    /**
+     * Converts an RGB color value to HSL. Conversion formula
+     * adapted from http://en.wikipedia.org/wiki/HSL_color_space.
+     * Assumes r, g, and b are contained in the set [0, 255] and
+     * returns h in the set [0, 360], s, and l in the set [0, 1].
+     */
     static fromRGBA(rgba: RGBA): HSLA;
     private static _hue2rgb;
+    /**
+     * Converts an HSL color value to RGB. Conversion formula
+     * adapted from http://en.wikipedia.org/wiki/HSL_color_space.
+     * Assumes h in the set [0, 360] s, and l are contained in the set [0, 1] and
+     * returns r, g, and b in the set [0, 255].
+     */
     static toRGBA(hsla: HSLA): RGBA;
 }
 export declare class HSVA {
     _hsvaBrand: void;
+    /**
+     * Hue: integer in [0, 360]
+     */
     readonly h: number;
+    /**
+     * Saturation: float in [0, 1]
+     */
     readonly s: number;
+    /**
+     * Value: float in [0, 1]
+     */
     readonly v: number;
+    /**
+     * Alpha: float in [0, 1]
+     */
     readonly a: number;
     constructor(h: number, s: number, v: number, a: number);
     static equals(a: HSVA, b: HSVA): boolean;
@@ -40,15 +88,56 @@ export declare class Color {
     get hsva(): HSVA;
     constructor(arg: RGBA | HSLA | HSVA);
     equals(other: Color | null): boolean;
+    /**
+     * http://www.w3.org/TR/WCAG20/#relativeluminancedef
+     * Returns the number in the set [0, 1]. O => Darkest Black. 1 => Lightest white.
+     */
     getRelativeLuminance(): number;
+    /**
+     * Reduces the "foreground" color on this "background" color unti it is
+     * below the relative luminace ratio.
+     * @returns the new foreground color
+     * @see https://github.com/xtermjs/xterm.js/blob/44f9fa39ae03e2ca6d28354d88a399608686770e/src/common/Color.ts#L315
+     */
     reduceRelativeLuminace(foreground: Color, ratio: number): Color;
+    /**
+     * Increases the "foreground" color on this "background" color unti it is
+     * below the relative luminace ratio.
+     * @returns the new foreground color
+     * @see https://github.com/xtermjs/xterm.js/blob/44f9fa39ae03e2ca6d28354d88a399608686770e/src/common/Color.ts#L335
+     */
     increaseRelativeLuminace(foreground: Color, ratio: number): Color;
     private static _relativeLuminanceForComponent;
+    /**
+     * http://www.w3.org/TR/WCAG20/#contrast-ratiodef
+     * Returns the contrast ration number in the set [1, 21].
+     */
     getContrastRatio(another: Color): number;
+    /**
+     *	http://24ways.org/2010/calculating-color-contrast
+     *  Return 'true' if darker color otherwise 'false'
+     */
     isDarker(): boolean;
+    /**
+     *	http://24ways.org/2010/calculating-color-contrast
+     *  Return 'true' if lighter color otherwise 'false'
+     */
     isLighter(): boolean;
     isLighterThan(another: Color): boolean;
     isDarkerThan(another: Color): boolean;
+    /**
+     * Based on xterm.js: https://github.com/xtermjs/xterm.js/blob/44f9fa39ae03e2ca6d28354d88a399608686770e/src/common/Color.ts#L288
+     *
+     * Given a foreground color and a background color, either increase or reduce the luminance of the
+     * foreground color until the specified contrast ratio is met. If pure white or black is hit
+     * without the contrast ratio being met, go the other direction using the background color as the
+     * foreground color and take either the first or second result depending on which has the higher
+     * contrast ratio.
+     *
+     * @param foreground The foreground color.
+     * @param ratio The contrast ratio to achieve.
+     * @returns The adjusted foreground color.
+     */
     ensureConstrast(foreground: Color, ratio: number): Color;
     lighten(factor: number): Color;
     darken(factor: number): Color;
@@ -57,6 +146,12 @@ export declare class Color {
     isOpaque(): boolean;
     opposite(): Color;
     blend(c: Color): Color;
+    /**
+     * Mixes the current color with the provided color based on the given factor.
+     * @param color The color to mix with
+     * @param factor The factor of mixing (0 means this color, 1 means the input color, 0.5 means equal mix)
+     * @returns A new color representing the mix
+     */
     mix(color: Color, factor?: number): Color;
     makeOpaque(opaqueBackground: Color): Color;
     flatten(...backgrounds: Color[]): Color;
@@ -83,10 +178,30 @@ export declare namespace Color {
             function formatRGBA(color: Color): string;
             function formatHSL(color: Color): string;
             function formatHSLA(color: Color): string;
+            /**
+             * Formats the color as #RRGGBB
+             */
             function formatHex(color: Color): string;
+            /**
+             * Formats the color as #RRGGBBAA
+             * If 'compact' is set, colors without transparancy will be printed as #RRGGBB
+             */
             function formatHexA(color: Color, compact?: boolean): string;
+            /**
+             * The default format will use HEX if opaque and RGBA otherwise.
+             */
             function format(color: Color): string;
+            /**
+             * Parse a CSS color and return a {@link Color}.
+             * @param css The CSS color to parse.
+             * @see https://drafts.csswg.org/css-color/#typedef-color
+             */
             function parse(css: string): Color | null;
+            /**
+             * Converts an Hex color value to a Color.
+             * returns r, g, and b are contained in the set [0, 255]
+             * @param hex string (#RGB, #RGBA, #RRGGBB or #RRGGBBAA).
+             */
             function parseHex(hex: string): Color | null;
         }
     }

package/vscode/src/vs/base/common/comparers.d.ts

@@ -1,12 +1,22 @@
+/** Compares filenames without distinguishing the name from the extension. Disambiguates by unicode comparison. */
 export declare function compareFileNames(one: string | null, other: string | null, caseSensitive?: boolean): number;
+/** Compares full filenames without grouping by case. */
 export declare function compareFileNamesDefault(one: string | null, other: string | null): number;
+/** Compares full filenames grouping uppercase names before lowercase. */
 export declare function compareFileNamesUpper(one: string | null, other: string | null): number;
+/** Compares full filenames grouping lowercase names before uppercase. */
 export declare function compareFileNamesLower(one: string | null, other: string | null): number;
+/** Compares full filenames by unicode value. */
 export declare function compareFileNamesUnicode(one: string | null, other: string | null): 1 | 0 | -1;
+/** Compares filenames by extension, then by name. Disambiguates by unicode comparison. */
 export declare function compareFileExtensions(one: string | null, other: string | null): number;
+/** Compares filenames by extension, then by full filename. Mixes uppercase and lowercase names together. */
 export declare function compareFileExtensionsDefault(one: string | null, other: string | null): number;
+/** Compares filenames by extension, then case, then full filename. Groups uppercase names before lowercase. */
 export declare function compareFileExtensionsUpper(one: string | null, other: string | null): number;
+/** Compares filenames by extension, then case, then full filename. Groups lowercase names before uppercase. */
 export declare function compareFileExtensionsLower(one: string | null, other: string | null): number;
+/** Compares filenames by case-insensitive extension unicode value, then by full filename unicode value. */
 export declare function compareFileExtensionsUnicode(one: string | null, other: string | null): 1 | 0 | -1;
 export declare function comparePaths(one: string, other: string, caseSensitive?: boolean): number;
 export declare function compareAnything(one: string, other: string, lookFor: string): number;

package/vscode/src/vs/base/common/dataTransfer.d.ts

@@ -17,9 +17,29 @@ export interface IReadonlyVSDataTransfer extends Iterable<readonly [
     string,
     IDataTransferItem
 ]> {
+    /**
+     * Get the total number of entries in this data transfer.
+     */
     get size(): number;
+    /**
+     * Check if this data transfer contains data for `mimeType`.
+     *
+     * This uses exact matching and does not support wildcards.
+     */
     has(mimeType: string): boolean;
+    /**
+     * Check if this data transfer contains data matching `pattern`.
+     *
+     * This allows matching for wildcards, such as `image/*`.
+     *
+     * Use the special `files` mime type to match any file in the data transfer.
+     */
     matches(pattern: string): boolean;
+    /**
+     * Retrieve the first entry for `mimeType`.
+     *
+     * Note that if you want to find all entries for a given mime type, use {@link IReadonlyVSDataTransfer.entries} instead.
+     */
     get(mimeType: string): IDataTransferItem | undefined;
 }
 export declare class VSDataTransfer implements IReadonlyVSDataTransfer {
@@ -28,9 +48,27 @@ export declare class VSDataTransfer implements IReadonlyVSDataTransfer {
     has(mimeType: string): boolean;
     matches(pattern: string): boolean;
     get(mimeType: string): IDataTransferItem | undefined;
+    /**
+     * Add a new entry to this data transfer.
+     *
+     * This does not replace existing entries for `mimeType`.
+     */
     append(mimeType: string, value: IDataTransferItem): void;
+    /**
+     * Set the entry for a given mime type.
+     *
+     * This replaces all existing entries for `mimeType`.
+     */
     replace(mimeType: string, value: IDataTransferItem): void;
+    /**
+     * Remove all entries for `mimeType`.
+     */
     delete(mimeType: string): void;
+    /**
+     * Iterate over all `[mime, item]` pairs in this data transfer.
+     *
+     * There may be multiple entries for each mime type.
+     */
     [Symbol.iterator](): IterableIterator<readonly [
         string,
         IDataTransferItem

package/vscode/src/vs/base/common/date.d.ts

@@ -1,6 +1,21 @@
 import { Lazy } from "./lazy.js";
+/**
+ * Create a localized difference of the time between now and the specified date.
+ * @param date The date to generate the difference from.
+ * @param appendAgoLabel Whether to append the " ago" to the end.
+ * @param useFullTimeWords Whether to use full words (eg. seconds) instead of
+ * shortened (eg. secs).
+ * @param disallowNow Whether to disallow the string "now" when the difference
+ * is less than 30 seconds.
+ */
 export declare function fromNow(date: number | Date, appendAgoLabel?: boolean, useFullTimeWords?: boolean, disallowNow?: boolean): string;
 export declare function fromNowByDay(date: number | Date, appendAgoLabel?: boolean, useFullTimeWords?: boolean): string;
+/**
+ * Gets a readable duration with intelligent/lossy precision. For example "40ms" or "3.040s")
+ * @param ms The duration to get in milliseconds.
+ * @param useFullTimeWords Whether to use full words (eg. seconds) instead of
+ * shortened (eg. secs).
+ */
 export declare function getDurationString(ms: number, useFullTimeWords?: boolean): string;
 export declare function toLocalISOString(date: Date): string;
 export declare const safeIntl: {

package/vscode/src/vs/base/common/diff/diff.d.ts

@@ -9,9 +9,25 @@ export interface ISequence {
     getStrictElement?(index: number): string;
 }
 export interface IDiffChange {
+    /**
+     * The position of the first element in the original sequence which
+     * this change affects.
+     */
     originalStart: number;
+    /**
+     * The number of elements from the original sequence which were
+     * affected.
+     */
     originalLength: number;
+    /**
+     * The position of the first element in the modified sequence which
+     * this change affects.
+     */
     modifiedStart: number;
+    /**
+     * The number of elements from the modified sequence which were
+     * affected (added).
+     */
     modifiedLength: number;
 }
 export interface IContinueProcessingPredicate {
@@ -21,6 +37,10 @@ export interface IDiffResult {
     quitEarly: boolean;
     changes: IDiffChange[];
 }
+/**
+ * An implementation of the difference algorithm described in
+ * "An O(ND) Difference Algorithm and its variations" by Eugene W. Myers
+ */
 export declare class LcsDiff {
     private readonly ContinueProcessingPredicate;
     private readonly _originalSequence;
@@ -32,6 +52,9 @@ export declare class LcsDiff {
     private readonly _modifiedElementsOrHash;
     private m_forwardHistory;
     private m_reverseHistory;
+    /**
+     * Constructs the DiffFinder
+     */
     constructor(originalSequence: ISequence, modifiedSequence: ISequence, continueProcessingPredicate?: IContinueProcessingPredicate | null);
     private static _isStringArray;
     private static _getElements;
@@ -41,10 +64,44 @@ export declare class LcsDiff {
     private OriginalElementsAreEqual;
     private ModifiedElementsAreEqual;
     ComputeDiff(pretty: boolean): IDiffResult;
+    /**
+     * Computes the differences between the original and modified input
+     * sequences on the bounded range.
+     * @returns An array of the differences between the two input sequences.
+     */
     private _ComputeDiff;
+    /**
+     * Private helper method which computes the differences on the bounded range
+     * recursively.
+     * @returns An array of the differences between the two input sequences.
+     */
     private ComputeDiffRecursive;
     private WALKTRACE;
+    /**
+     * Given the range to compute the diff on, this method finds the point:
+     * (midOriginal, midModified)
+     * that exists in the middle of the LCS of the two sequences and
+     * is the point at which the LCS problem may be broken down recursively.
+     * This method will try to keep the LCS trace in memory. If the LCS recursion
+     * point is calculated and the full trace is available in memory, then this method
+     * will return the change list.
+     * @param originalStart The start bound of the original sequence range
+     * @param originalEnd The end bound of the original sequence range
+     * @param modifiedStart The start bound of the modified sequence range
+     * @param modifiedEnd The end bound of the modified sequence range
+     * @param midOriginal The middle point of the original sequence range
+     * @param midModified The middle point of the modified sequence range
+     * @returns The diff changes, if available, otherwise null
+     */
     private ComputeRecursionPoint;
+    /**
+     * Shifts the given changes to provide a more intuitive diff.
+     * While the first element in a diff matches the first element after the diff,
+     * we shift the diff down.
+     *
+     * @param changes The list of changes to shift
+     * @returns The shifted changes
+     */
     private PrettifyChanges;
     private _findBetterContiguousSequence;
     private _contiguousSequenceScore;
@@ -53,8 +110,41 @@ export declare class LcsDiff {
     private _ModifiedIsBoundary;
     private _ModifiedRegionIsBoundary;
     private _boundaryScore;
+    /**
+     * Concatenates the two input DiffChange lists and returns the resulting
+     * list.
+     * @param The left changes
+     * @param The right changes
+     * @returns The concatenated list
+     */
     private ConcatenateChanges;
+    /**
+     * Returns true if the two changes overlap and can be merged into a single
+     * change
+     * @param left The left change
+     * @param right The right change
+     * @param mergedChange The merged change if the two overlap, null otherwise
+     * @returns True if the two changes overlap
+     */
     private ChangesOverlap;
+    /**
+     * Helper method used to clip a diagonal index to the range of valid
+     * diagonals. This also decides whether or not the diagonal index,
+     * if it exceeds the boundary, should be clipped to the boundary or clipped
+     * one inside the boundary depending on the Even/Odd status of the boundary
+     * and numDifferences.
+     * @param diagonal The index of the diagonal to clip.
+     * @param numDifferences The current number of differences being iterated upon.
+     * @param diagonalBaseIndex The base reference diagonal.
+     * @param numDiagonals The total number of diagonals.
+     * @returns The clipped diagonal index.
+     */
     private ClipDiagonalBound;
 }
+/**
+ * Computes the Levenshtein distance between two strings.
+ * @param firstString - The first string.
+ * @param secondString - The second string.
+ * @returns The Levenshtein distance.
+ */
 export declare function computeLevenshteinDistance(firstString: string, secondString: string): number;

package/vscode/src/vs/base/common/diff/diffChange.d.ts

@@ -1,9 +1,38 @@
+/**
+ * Represents information about a specific difference between two sequences.
+ */
 export declare class DiffChange {
+    /**
+     * The position of the first element in the original sequence which
+     * this change affects.
+     */
     originalStart: number;
+    /**
+     * The number of elements from the original sequence which were
+     * affected.
+     */
     originalLength: number;
+    /**
+     * The position of the first element in the modified sequence which
+     * this change affects.
+     */
     modifiedStart: number;
+    /**
+     * The number of elements from the modified sequence which were
+     * affected (added).
+     */
     modifiedLength: number;
+    /**
+     * Constructs a new DiffChange with the given sequence information
+     * and content.
+     */
     constructor(originalStart: number, originalLength: number, modifiedStart: number, modifiedLength: number);
+    /**
+     * The end point (exclusive) of the change in the original sequence.
+     */
     getOriginalEnd(): number;
+    /**
+     * The end point (exclusive) of the change in the modified sequence.
+     */
     getModifiedEnd(): number;
 }

package/vscode/src/vs/base/common/equals.d.ts

@@ -1,11 +1,37 @@
 export type EqualityComparer<T> = (a: T, b: T) => boolean;
+/**
+ * Compares two items for equality using strict equality.
+*/
 export declare const strictEquals: EqualityComparer<any>;
+/**
+ * Checks if the items of two arrays are equal.
+ * By default, strict equality is used to compare elements, but a custom equality comparer can be provided.
+ */
 export declare function itemsEquals<T>(itemEquals?: EqualityComparer<T>): EqualityComparer<readonly T[]>;
+/**
+ * Two items are considered equal, if their stringified representations are equal.
+*/
 export declare function jsonStringifyEquals<T>(): EqualityComparer<T>;
+/**
+ * Uses `item.equals(other)` to determine equality.
+ */
 export declare function itemEquals<T extends {
     equals(other: T): boolean;
 }>(): EqualityComparer<T>;
+/**
+ * Checks if two items are both null or undefined, or are equal according to the provided equality comparer.
+*/
 export declare function equalsIfDefined<T>(v1: T | undefined | null, v2: T | undefined | null, equals: EqualityComparer<T>): boolean;
+/**
+ * Returns an equality comparer that checks if two items are both null or undefined, or are equal according to the provided equality comparer.
+*/
 export declare function equalsIfDefined<T>(equals: EqualityComparer<T>): EqualityComparer<T | undefined | null>;
+/**
+ * Drills into arrays (items ordered) and objects (keys unordered) and uses strict equality on everything else.
+*/
 export declare function structuralEquals<T>(a: T, b: T): boolean;
+/**
+ * `getStructuralKey(a) === getStructuralKey(b) <=> structuralEquals(a, b)`
+ * (assuming that a and b are not cyclic structures and nothing extends globalThis Array).
+*/
 export declare function getStructuralKey(t: unknown): string;

package/vscode/src/vs/base/common/errorMessage.d.ts

@@ -1,4 +1,10 @@
 import { IAction } from "./actions.js";
+/**
+ * Tries to generate a human readable error message out of the error. If the verbose parameter
+ * is set to true, the error message will include stacktrace details if provided.
+ *
+ * @returns A string containing the error message.
+ */
 export declare function toErrorMessage(error?: any, verbose?: boolean): string;
 export interface IErrorWithActions extends Error {
     actions: IAction[];

package/vscode/src/vs/base/common/errors.d.ts

@@ -17,8 +17,20 @@ export declare class ErrorHandler {
     onUnexpectedExternalError(e: any): void;
 }
 export declare const errorHandler: ErrorHandler;
+/** @skipMangle */
 export declare function setUnexpectedErrorHandler(newUnexpectedErrorHandler: (e: any) => void): void;
+/**
+ * Returns if the error is a SIGPIPE error. SIGPIPE errors should generally be
+ * logged at most once, to avoid a loop.
+ *
+ * @see https://github.com/microsoft/vscode-remote-release/issues/6481
+ */
 export declare function isSigPipeError(e: unknown): e is Error;
+/**
+ * This function should only be called with errors that indicate a bug in the product.
+ * E.g. buggy extensions/invalid user-input/network issues should not be able to trigger this code path.
+ * If they are, this indicates there is also a bug in the product.
+*/
 export declare function onBugIndicatingError(e: any): undefined;
 export declare function onUnexpectedError(e: any): undefined;
 export declare function onUnexpectedExternalError(e: any): undefined;
@@ -51,6 +63,9 @@ export interface V8CallSite {
     toString(): string;
 }
 export declare const canceledName = "Canceled";
+/**
+ * Checks if the given error is a promise in canceled state
+ */
 export declare function isCancellationError(error: any): boolean;
 export declare class CancellationError extends Error {
     constructor();
@@ -60,6 +75,9 @@ export declare class PendingMigrationError extends Error {
     static is(error: unknown): error is PendingMigrationError;
     constructor(message: string);
 }
+/**
+ * @deprecated use {@link CancellationError `new CancellationError()`} instead
+ */
 export declare function canceled(): Error;
 export declare function illegalArgument(name?: string): Error;
 export declare function illegalState(name?: string): Error;
@@ -76,12 +94,20 @@ export declare class NotSupportedError extends Error {
 export declare class ExpectedError extends Error {
     readonly isExpected = true;
 }
+/**
+ * Error that when thrown won't be logged in telemetry as an unhandled error.
+ */
 export declare class ErrorNoTelemetry extends Error {
     readonly name: string;
     constructor(msg?: string);
     static fromError(err: Error): ErrorNoTelemetry;
     static isErrorNoTelemetry(err: Error): err is ErrorNoTelemetry;
 }
+/**
+ * This error indicates a bug.
+ * Do not throw this for invalid user input.
+ * Only catch this error to recover gracefully from bugs.
+ */
 export declare class BugIndicatingError extends Error {
     constructor(message?: string);
 }