@codingame/monaco-vscode-api 20.1.1 → 20.2.1

package/vscode/src/vs/editor/browser/editorDom.d.ts

@@ -2,6 +2,9 @@ import { StandardMouseEvent } from "../../base/browser/mouseEvent.js";
 import { Disposable, IDisposable } from "../../base/common/lifecycle.js";
 import { ICodeEditor } from "./editorBrowser.js";
 import { ThemeColor } from "../../base/common/themables.js";
+/**
+ * Coordinates relative to the whole document (e.g. mouse event's pageX and pageY)
+ */
 export declare class PageCoordinates {
     readonly x: number;
     readonly y: number;
@@ -9,6 +12,13 @@ export declare class PageCoordinates {
     constructor(x: number, y: number);
     toClientCoordinates(targetWindow: Window): ClientCoordinates;
 }
+/**
+ * Coordinates within the application's client area (i.e. origin is document's scroll position).
+ *
+ * For example, clicking in the top-left corner of the client area will
+ * always result in a mouse event with a client.x value of 0, regardless
+ * of whether the page is scrolled horizontally.
+ */
 export declare class ClientCoordinates {
     readonly clientX: number;
     readonly clientY: number;
@@ -16,6 +26,9 @@ export declare class ClientCoordinates {
     constructor(clientX: number, clientY: number);
     toPageCoordinates(targetWindow: Window): PageCoordinates;
 }
+/**
+ * The position of the editor in the page.
+ */
 export declare class EditorPagePosition {
     readonly x: number;
     readonly y: number;
@@ -24,6 +37,12 @@ export declare class EditorPagePosition {
     _editorPagePositionBrand: void;
     constructor(x: number, y: number, width: number, height: number);
 }
+/**
+ * Coordinates relative to the (top;left) of the editor that can be used safely with other internal editor metrics.
+ * **NOTE**: This position is obtained by taking page coordinates and transforming them relative to the
+ * editor's (top;left) position in a way in which scale transformations are taken into account.
+ * **NOTE**: These coordinates could be negative if the mouse position is outside the editor.
+ */
 export declare class CoordinatesRelativeToEditor {
     readonly x: number;
     readonly y: number;
@@ -34,9 +53,24 @@ export declare function createEditorPagePosition(editorViewDomNode: HTMLElement)
 export declare function createCoordinatesRelativeToEditor(editorViewDomNode: HTMLElement, editorPagePosition: EditorPagePosition, pos: PageCoordinates): CoordinatesRelativeToEditor;
 export declare class EditorMouseEvent extends StandardMouseEvent {
     _editorMouseEventBrand: void;
+    /**
+     * If the event is a result of using `setPointerCapture`, the `event.target`
+     * does not necessarily reflect the position in the editor.
+     */
     readonly isFromPointerCapture: boolean;
+    /**
+     * Coordinates relative to the whole document.
+     */
     readonly pos: PageCoordinates;
+    /**
+     * Editor's coordinates relative to the whole document.
+     */
     readonly editorPos: EditorPagePosition;
+    /**
+     * Coordinates relative to the (top;left) of the editor.
+     * *NOTE*: These coordinates are preferred because they take into account transformations applied to the editor.
+     * *NOTE*: These coordinates could be negative if the mouse position is outside the editor.
+     */
     readonly relativePos: CoordinatesRelativeToEditor;
     constructor(e: MouseEvent, isFromPointerCapture: boolean, editorViewDomNode: HTMLElement);
 }
@@ -68,6 +102,11 @@ export declare class GlobalEditorPointerMoveMonitor extends Disposable {
     startMonitoring(initialElement: Element, pointerId: number, initialButtons: number, pointerMoveCallback: (e: EditorMouseEvent) => void, onStopCallback: (browserEvent?: PointerEvent | KeyboardEvent) => void): void;
     stopMonitoring(): void;
 }
+/**
+ * A helper to create dynamic css rules, bound to a class name.
+ * Rules are reused.
+ * Reference counting and delayed garbage collection ensure that no rules leak.
+*/
 export declare class DynamicCssRules {
     private readonly _editor;
     private static _idPool;

package/vscode/src/vs/editor/browser/editorExtensions.d.ts

@@ -18,10 +18,31 @@ export type DiffEditorContributionCtor = IConstructorSignature<IDiffEditorContri
     IDiffEditor
 ]>;
 export declare enum EditorContributionInstantiation {
+    /**
+     * The contribution is created eagerly when the {@linkcode ICodeEditor} is instantiated.
+     * Only Eager contributions can participate in saving or restoring of view state.
+     */
     Eager = 0,
+    /**
+     * The contribution is created at the latest 50ms after the first render after attaching a text model.
+     * If the contribution is explicitly requested via `getContribution`, it will be instantiated sooner.
+     * If there is idle time available, it will be instantiated sooner.
+     */
     AfterFirstRender = 1,
+    /**
+     * The contribution is created before the editor emits events produced by user interaction (mouse events, keyboard events).
+     * If the contribution is explicitly requested via `getContribution`, it will be instantiated sooner.
+     * If there is idle time available, it will be instantiated sooner.
+     */
     BeforeFirstInteraction = 2,
+    /**
+     * The contribution is created when there is idle time available, at the latest 5000ms after the editor creation.
+     * If the contribution is explicitly requested via `getContribution`, it will be instantiated sooner.
+     */
     Eventually = 3,
+    /**
+     * The contribution is created only when explicitly requested via `getContribution`.
+     */
     Lazy = 4
 }
 export interface IEditorContributionDescription {
@@ -36,6 +57,9 @@ export interface IDiffEditorContributionDescription {
 export interface ICommandKeybindingsOptions extends IKeybindings {
     kbExpr?: ContextKeyExpression | null;
     weight: number;
+    /**
+     * the default keybinding arguments
+     */
     args?: any;
 }
 export interface ICommandMenuOptions {
@@ -64,12 +88,25 @@ export declare abstract class Command {
     private _registerMenuItem;
     abstract runCommand(accessor: ServicesAccessor, args: any): void | Promise<void>;
 }
+/**
+ * Potential override for a command.
+ *
+ * @return `true` or a Promise if the command was successfully run. This stops other overrides from being executed.
+ */
 export type CommandImplementation = (accessor: ServicesAccessor, args: unknown) => boolean | Promise<void>;
 export declare class MultiCommand extends Command {
     private readonly _implementations;
+    /**
+     * A higher priority gets to be looked at first
+     */
     addImplementation(priority: number, name: string, implementation: CommandImplementation, when?: ContextKeyExpression): IDisposable;
     runCommand(accessor: ServicesAccessor, args: any): void | Promise<void>;
 }
+/**
+ * A command that delegates to another command's implementation.
+ *
+ * This lets different commands be registered but share the same implementation
+ */
 export declare class ProxyCommand extends Command {
     private readonly command;
     constructor(command: Command, opts: ICommandOptions);
@@ -82,6 +119,9 @@ export interface EditorControllerCommand<T extends IEditorContribution> {
     new (opts: IContributionCommandOptions<T>): EditorCommand;
 }
 export declare abstract class EditorCommand extends Command {
+    /**
+     * Create a command class that is bound to a certain editor contribution.
+     */
     static bindToContribution<T extends IEditorContribution>(controllerGetter: (editor: ICodeEditor) => T | null): EditorControllerCommand<T>;
     static runEditorCommand(accessor: ServicesAccessor, args: any, precondition: ContextKeyExpression | undefined, runner: (accessor: ServicesAccessor, editor: ICodeEditor, args: any) => void | Promise<void>): void | Promise<void>;
     runCommand(accessor: ServicesAccessor, args: any): void | Promise<void>;
@@ -114,6 +154,9 @@ export declare abstract class EditorAction extends EditorCommand {
 export type EditorActionImplementation = (accessor: ServicesAccessor, editor: ICodeEditor, args: any) => boolean | Promise<void>;
 export declare class MultiEditorAction extends EditorAction {
     private readonly _implementations;
+    /**
+     * A higher priority gets to be looked at first
+     */
     addImplementation(priority: number, implementation: EditorActionImplementation): IDisposable;
     run(accessor: ServicesAccessor, editor: ICodeEditor, args: any): void | Promise<void>;
 }
@@ -128,9 +171,17 @@ export declare function registerEditorAction<T extends EditorAction>(ctor: {
 }): T;
 export declare function registerMultiEditorAction<T extends MultiEditorAction>(action: T): T;
 export declare function registerInstantiatedEditorAction(editorAction: EditorAction): void;
+/**
+ * Registers an editor contribution. Editor contributions have a lifecycle which is bound
+ * to a specific code editor instance.
+ */
 export declare function registerEditorContribution<Services extends BrandedService[]>(id: string, ctor: {
     new (editor: ICodeEditor, ...services: Services): IEditorContribution;
 }, instantiation: EditorContributionInstantiation): void;
+/**
+ * Registers a diff editor contribution. Diff editor contributions have a lifecycle which
+ * is bound to a specific diff editor instance.
+ */
 export declare function registerDiffEditorContribution<Services extends BrandedService[]>(id: string, ctor: {
     new (editor: IDiffEditor, ...services: Services): IEditorContribution;
 }): void;

package/vscode/src/vs/editor/browser/gpu/atlas/atlas.d.ts

@@ -1,28 +1,93 @@
 import type { NKeyMap } from "../../../../base/common/map.js";
 import type { IBoundingBox, IRasterizedGlyph } from "../raster/raster.js";
+/**
+ * Information about a {@link IRasterizedGlyph rasterized glyph} that has been drawn to a texture
+ * atlas page.
+ */
 export interface ITextureAtlasPageGlyph {
+    /**
+     * The page index of the texture atlas page that the glyph was drawn to.
+     */
     pageIndex: number;
+    /**
+     * The index of the glyph in the texture atlas page.
+     */
     glyphIndex: number;
+    /** The x coordinate of the glyph on the texture atlas page. */
     x: number;
+    /** The y coordinate of the glyph on the texture atlas page. */
     y: number;
+    /** The width of the glyph in pixels. */
     w: number;
+    /** The height of the glyph in pixels. */
     h: number;
+    /** The x offset from {@link x} of the glyph's origin. */
     originOffsetX: number;
+    /** The y offset from {@link y} of the glyph's origin. */
     originOffsetY: number;
+    /**
+     * The distance from the glyph baseline to the top of the highest bounding rectangle of all
+     * fonts used to render the text.
+     *
+     * @see {@link TextMetrics.fontBoundingBoxAscent}
+     */
     fontBoundingBoxAscent: number;
+    /**
+     * The distance from the glyph baseline to the bottom of the bounding rectangle of all fonts
+     * used to render the text.
+     *
+     * @see {@link TextMetrics.fontBoundingBoxDescent}
+     */
     fontBoundingBoxDescent: number;
 }
+/**
+ * A texture atlas allocator is responsible for taking rasterized glyphs, drawing them to a texture
+ * atlas page canvas and return information on the texture atlas glyph.
+ */
 export interface ITextureAtlasAllocator {
+    /**
+     * Allocates a rasterized glyph to the canvas, drawing it and returning information on its
+     * position in the canvas. This will return undefined if the glyph does not fit on the canvas.
+     */
     allocate(rasterizedGlyph: Readonly<IRasterizedGlyph>): Readonly<ITextureAtlasPageGlyph> | undefined;
+    /**
+     * Gets a usage preview of the atlas for debugging purposes.
+     */
     getUsagePreview(): Promise<Blob>;
+    /**
+     * Gets statistics about the allocator's current state for debugging purposes.
+     */
     getStats(): string;
 }
+/**
+ * A texture atlas page that can be read from but not modified.
+ */
 export interface IReadableTextureAtlasPage {
+    /**
+     * A unique identifier for the current state of the texture atlas page. This is a number that
+     * increments whenever a glyph is drawn to the page.
+     */
     readonly version: number;
+    /**
+     * A bounding box representing the area of the texture atlas page that is currently in use.
+     */
     readonly usedArea: Readonly<IBoundingBox>;
+    /**
+     * An iterator over all glyphs that have been drawn to the page. This will iterate through
+     * glyphs in the order they have been drawn.
+     */
     readonly glyphs: IterableIterator<Readonly<ITextureAtlasPageGlyph>>;
+    /**
+     * The source canvas for the texture atlas page.
+     */
     readonly source: OffscreenCanvas;
+    /**
+     * Gets a usage preview of the atlas for debugging purposes.
+     */
     getUsagePreview(): Promise<Blob>;
+    /**
+     * Gets statistics about the allocator's current state for debugging purposes.
+     */
     getStats(): string;
 }
 export declare enum UsagePreviewColors {

package/vscode/src/vs/editor/browser/gpu/atlas/textureAtlas.d.ts

@@ -10,6 +10,7 @@ export interface ITextureAtlasOptions {
     allocatorType?: AllocatorType;
 }
 export declare class TextureAtlas extends Disposable {
+    /** The maximum texture size supported by the GPU. */
     private readonly _maxTextureSize;
     private readonly _decorationStyleCache;
     private readonly _themeService;
@@ -18,14 +19,31 @@ export declare class TextureAtlas extends Disposable {
     private readonly _warmUpTask;
     private readonly _warmedUpRasterizers;
     private readonly _allocatorType;
+    /**
+     * The maximum number of texture atlas pages. This is currently a hard static cap that must not
+     * be reached.
+     */
     static readonly maximumPageCount = 16;
+    /**
+     * The main texture atlas pages which are both larger textures and more efficiently packed
+     * relative to the scratch page. The idea is the main pages are drawn to and uploaded to the GPU
+     * much less frequently so as to not drop frames.
+     */
     private readonly _pages;
     get pages(): IReadableTextureAtlasPage[];
     readonly pageSize: number;
+    /**
+     * A maps of glyph keys to the page to start searching for the glyph. This is set before
+     * searching to have as little runtime overhead (branching, intermediate variables) as possible,
+     * so it is not guaranteed to be the actual page the glyph is on. But it is guaranteed that all
+     * pages with a lower index do not contain the glyph.
+     */
     private readonly _glyphPageIndex;
     private readonly _onDidDeleteGlyphs;
     readonly onDidDeleteGlyphs: Event<void>;
-    constructor(_maxTextureSize: number, options: ITextureAtlasOptions | undefined, _decorationStyleCache: DecorationStyleCache, _themeService: IThemeService, _instantiationService: IInstantiationService);
+    constructor(
+    /** The maximum texture size supported by the GPU. */
+    _maxTextureSize: number, options: ITextureAtlasOptions | undefined, _decorationStyleCache: DecorationStyleCache, _themeService: IThemeService, _instantiationService: IInstantiationService);
     private _initFirstPage;
     clear(): void;
     getGlyph(rasterizer: IGlyphRasterizer, chars: string, tokenMetadata: number, decorationStyleSetId: number, x: number): Readonly<ITextureAtlasPageGlyph>;
@@ -33,5 +51,9 @@ export declare class TextureAtlas extends Disposable {
     private _getGlyphFromNewPage;
     getUsagePreview(): Promise<Blob[]>;
     getStats(): string[];
+    /**
+     * Warms up the atlas by rasterizing all printable ASCII characters for each token color. This
+     * is distrubuted over multiple idle callbacks to avoid blocking the main thread.
+     */
     private _warmUpAtlas;
 }

package/vscode/src/vs/editor/browser/gpu/atlas/textureAtlasPage.d.ts

@@ -8,6 +8,10 @@ export declare class TextureAtlasPage extends Disposable implements IReadableTex
     private readonly _logService;
     private _version;
     get version(): number;
+    /**
+     * The maximum number of glyphs that can be drawn to the page. This is currently a hard static
+     * cap that must not be reached as it will cause the GPU buffer to overflow.
+     */
     static readonly maximumGlyphCount = 5000;
     private _usedArea;
     get usedArea(): Readonly<IBoundingBox>;

package/vscode/src/vs/editor/browser/gpu/atlas/textureAtlasShelfAllocator.d.ts

@@ -1,10 +1,15 @@
 import type { IRasterizedGlyph } from "../raster/raster.js";
 import { type ITextureAtlasAllocator, type ITextureAtlasPageGlyph } from "./atlas.js";
+/**
+ * The shelf allocator is a simple allocator that places glyphs in rows, starting a new row when the
+ * current row is full. Due to its simplicity, it can waste space but it is very fast.
+ */
 export declare class TextureAtlasShelfAllocator implements ITextureAtlasAllocator {
     private readonly _canvas;
     private readonly _textureIndex;
     private readonly _ctx;
     private _currentRow;
+    /** A set of all glyphs allocated, this is only tracked to enable debug related functionality */
     private readonly _allocatedGlyphs;
     private _nextIndex;
     constructor(_canvas: OffscreenCanvas, _textureIndex: number);

package/vscode/src/vs/editor/browser/gpu/atlas/textureAtlasSlabAllocator.d.ts

@@ -4,6 +4,15 @@ export interface TextureAtlasSlabAllocatorOptions {
     slabW?: number;
     slabH?: number;
 }
+/**
+ * The slab allocator is a more complex allocator that places glyphs in square slabs of a fixed
+ * size. Slabs are defined by a small range of glyphs sizes they can house, this places like-sized
+ * glyphs in the same slab which reduces wasted space.
+ *
+ * Slabs also may contain "unused" regions on the left and bottom depending on the size of the
+ * glyphs they include. This space is used to place very thin or short glyphs, which would otherwise
+ * waste a lot of space in their own slab.
+ */
 export declare class TextureAtlasSlabAllocator implements ITextureAtlasAllocator {
     private readonly _canvas;
     private readonly _textureIndex;
@@ -13,6 +22,7 @@ export declare class TextureAtlasSlabAllocator implements ITextureAtlasAllocator
     private readonly _unusedRects;
     private readonly _openRegionsByHeight;
     private readonly _openRegionsByWidth;
+    /** A set of all glyphs allocated, this is only tracked to enable debug related functionality */
     private readonly _allocatedGlyphs;
     private _slabW;
     private _slabH;

package/vscode/src/vs/editor/browser/gpu/bufferDirtyTracker.d.ts

@@ -1,15 +1,35 @@
 export interface IBufferDirtyTrackerReader {
+    /**
+     * The index of the first dirty index.
+     */
     readonly dataOffset: number | undefined;
+    /**
+     * The index of the last dirty index (inclusive).
+     */
     readonly dirtySize: number | undefined;
+    /**
+     * Whether the buffer is dirty.
+     */
     readonly isDirty: boolean;
+    /**
+     * Clear the dirty state.
+     */
     clear(): void;
 }
+/**
+ * A simple tracker for dirty regions in a buffer.
+ */
 export declare class BufferDirtyTracker implements IBufferDirtyTrackerReader {
     private _startIndex;
     private _endIndex;
     get dataOffset(): number | undefined;
     get dirtySize(): number | undefined;
     get isDirty(): boolean;
+    /**
+     * Flag the index(es) as modified. Returns the index flagged.
+     * @param index An index to flag.
+     * @param length An optional length to flag. Defaults to 1.
+     */
     flag(index: number, length?: number): number;
     private _flag;
     clear(): void;

package/vscode/src/vs/editor/browser/gpu/contentSegmenter.d.ts

@@ -1,6 +1,12 @@
 import type { ViewLineRenderingData } from "../../common/viewModel.js";
 import type { ViewLineOptions } from "../viewParts/viewLines/viewLineOptions.js";
 export interface IContentSegmenter {
+    /**
+     * Gets the content segment at an index within the line data's contents. This will be undefined
+     * when the index should not be rendered, ie. when it's part of an earlier segment like the tail
+     * end of an emoji, or when the line is not that long.
+     * @param index The index within the line data's content string.
+     */
     getSegmentAtIndex(index: number): string | undefined;
     getSegmentData(index: number): Intl.SegmentData | undefined;
 }

package/vscode/src/vs/editor/browser/gpu/css/decorationCssRuleExtractor.d.ts

@@ -1,4 +1,7 @@
 import { Disposable } from "../../../../base/common/lifecycle.js";
+/**
+ * Extracts CSS rules that would be applied to certain decoration classes.
+ */
 export declare class DecorationCssRuleExtractor extends Disposable {
     private _container;
     private _dummyElement;

package/vscode/src/vs/editor/browser/gpu/css/decorationStyleCache.d.ts

@@ -1,9 +1,21 @@
 export interface IDecorationStyleSet {
+    /**
+     * A 24-bit number representing `color`.
+     */
     color: number | undefined;
+    /**
+     * Whether the text should be rendered in bold.
+     */
     bold: boolean | undefined;
+    /**
+     * A number between 0 and 1 representing the opacity of the text.
+     */
     opacity: number | undefined;
 }
 export interface IDecorationStyleCacheEntry extends IDecorationStyleSet {
+    /**
+     * A unique identifier for this set of styles.
+     */
     id: number;
 }
 export declare class DecorationStyleCache {

package/vscode/src/vs/editor/browser/gpu/css/media/decorationCssRuleExtractor.css

@@ -1,3 +1,8 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
 .monaco-editor .monaco-decoration-css-rule-extractor {
 	visibility: hidden;
 	pointer-events: none;

package/vscode/src/vs/editor/browser/gpu/gpu.d.ts

@@ -23,6 +23,9 @@ export interface IGpuRenderStrategy extends IDisposable {
     onLinesInserted(e: ViewLinesInsertedEvent): boolean;
     onLinesChanged(e: ViewLinesChangedEvent): boolean;
     onScrollChanged(e?: ViewScrollChangedEvent): boolean;
+    /**
+     * Resets the render strategy, clearing all data and setting up for a new frame.
+     */
     reset(): void;
     update(viewportData: ViewportData, viewLineOptions: ViewLineOptions): number;
     draw(pass: GPURenderPassEncoder, viewportData: ViewportData): void;

package/vscode/src/vs/editor/browser/gpu/objectCollectionBuffer.d.ts

@@ -8,16 +8,49 @@ export type ObjectCollectionPropertyValues<T extends ObjectCollectionBufferPrope
     [K in T[number]["name"]]: number;
 };
 export interface IObjectCollectionBuffer<T extends ObjectCollectionBufferPropertySpec[]> extends IDisposable {
+    /**
+     * The underlying buffer. This **should not** be modified externally.
+     */
     readonly buffer: ArrayBufferLike;
+    /**
+     * A view of the underlying buffer. This **should not** be modified externally.
+     */
     readonly view: Float32Array;
+    /**
+     * The size of the used portion of the buffer (in bytes).
+     */
     readonly bufferUsedSize: number;
+    /**
+     * The size of the used portion of the view (in float32s).
+     */
     readonly viewUsedSize: number;
+    /**
+     * The number of entries in the buffer.
+     */
     readonly entryCount: number;
+    /**
+     * A tracker for dirty regions in the buffer.
+     */
     readonly dirtyTracker: IBufferDirtyTrackerReader;
+    /**
+     * Fires when the buffer is modified.
+     */
     readonly onDidChange: Event<void>;
+    /**
+     * Fires when the buffer is recreated.
+     */
     readonly onDidChangeBuffer: Event<void>;
+    /**
+     * Creates an entry in the collection. This will return a managed object that can be modified
+     * which will update the underlying buffer.
+     * @param data The data of the entry.
+     */
     createEntry(data: ObjectCollectionPropertyValues<T>): IObjectCollectionBufferEntry<T>;
 }
+/**
+ * An entry in an {@link ObjectCollectionBuffer}. Property values on the entry can be changed and
+ * their values will be updated automatically in the buffer.
+ */
 export interface IObjectCollectionBufferEntry<T extends ObjectCollectionBufferPropertySpec[]> extends IDisposable {
     set(propertyName: T[number]["name"], value: number): void;
     get(propertyName: T[number]["name"]): number;

package/vscode/src/vs/editor/browser/gpu/raster/glyphRasterizer.d.ts

@@ -15,6 +15,10 @@ export declare class GlyphRasterizer extends Disposable implements IGlyphRasteri
     private _workGlyphConfig;
     private _antiAliasing;
     constructor(fontSize: number, fontFamily: string, devicePixelRatio: number, _decorationStyleCache: DecorationStyleCache);
+    /**
+     * Rasterizes a glyph. Note that the returned object is reused across different glyphs and
+     * therefore is only safe for synchronous access.
+     */
     rasterizeGlyph(chars: string, tokenMetadata: number, decorationStyleSetId: number, colorMap: string[]): Readonly<IRasterizedGlyph>;
     _rasterizeGlyph(chars: string, tokenMetadata: number, decorationStyleSetId: number, colorMap: string[]): Readonly<IRasterizedGlyph>;
     private _clearColor;

package/vscode/src/vs/editor/browser/gpu/raster/raster.d.ts

@@ -1,22 +1,69 @@
 export interface IGlyphRasterizer {
+    /**
+     * A unique identifier for the rasterizer.
+     */
     readonly id: number;
+    /**
+     * An identifier for properties inherent to rendering with this rasterizer. This will be the
+     * same as other rasterizer cache keys provided they share the same property values in question.
+     */
     readonly cacheKey: string;
+    /**
+     * Rasterizes a glyph.
+     * @param chars The character(s) to rasterize. This can be a single character, a ligature, an
+     * emoji, etc.
+     * @param tokenMetadata The token metadata of the glyph to rasterize. See {@link MetadataConsts}
+     * for how this works.
+     * @param decorationStyleSetId The id of the decoration style sheet. Zero means no decoration.
+     * @param colorMap A theme's color map.
+     */
     rasterizeGlyph(chars: string, tokenMetadata: number, decorationStyleSetId: number, colorMap: string[]): Readonly<IRasterizedGlyph>;
     getTextMetrics(text: string): TextMetrics;
 }
+/**
+ * A simple bounding box in a 2D plane.
+ */
 export interface IBoundingBox {
+    /** The left x coordinate (inclusive). */
     left: number;
+    /** The top y coordinate (inclusive). */
     top: number;
+    /** The right x coordinate (inclusive). */
     right: number;
+    /** The bottom y coordinate (inclusive). */
     bottom: number;
 }
+/**
+ * A glyph that has been rasterized to a canvas.
+ */
 export interface IRasterizedGlyph {
+    /**
+     * The source canvas the glyph was rasterized to.
+     */
     source: OffscreenCanvas;
+    /**
+     * The bounding box of the glyph within {@link source}.
+     */
     boundingBox: IBoundingBox;
+    /**
+     * The offset to the glyph's origin (where it should be drawn to).
+     */
     originOffset: {
         x: number;
         y: number;
     };
+    /**
+     * The distance from the glyph baseline to the top of the highest bounding rectangle of all
+     * fonts used to render the text.
+     *
+     * @see {@link TextMetrics.fontBoundingBoxAscent}
+     */
     fontBoundingBoxAscent: number;
+    /**
+     * The distance from the glyph baseline to the bottom of the bounding rectangle of all fonts
+     * used to render the text.
+     *
+     * @see {@link TextMetrics.fontBoundingBoxDescent}
+     */
     fontBoundingBoxDescent: number;
 }

package/vscode/src/vs/editor/browser/gpu/renderStrategy/fullFileRenderStrategy.d.ts

@@ -5,12 +5,27 @@ import type { ViewLineOptions } from "../../viewParts/viewLines/viewLineOptions.
 import { GlyphRasterizer } from "../raster/glyphRasterizer.js";
 import { ViewGpuContext } from "../viewGpuContext.js";
 import { BaseRenderStrategy } from "./baseRenderStrategy.js";
+/**
+ * A render strategy that tracks a large buffer, uploading only dirty lines as they change and
+ * leveraging heavy caching. This is the most performant strategy but has limitations around long
+ * lines and too many lines.
+ */
 export declare class FullFileRenderStrategy extends BaseRenderStrategy {
+    /**
+     * The hard cap for line count that can be rendered by the GPU renderer.
+     */
     static readonly maxSupportedLines = 3000;
+    /**
+     * The hard cap for line columns that can be rendered by the GPU renderer.
+     */
     static readonly maxSupportedColumns = 200;
     readonly type = "fullfile";
     readonly wgsl: string;
     private _cellBindBuffer;
+    /**
+     * The cell value buffers, these hold the cells and their glyphs. It's double buffers such that
+     * the thread doesn't block when one is being uploaded to the GPU.
+     */
     private _cellValueBuffers;
     private _activeDoubleBufferIndex;
     private readonly _upToDateLines;
@@ -40,5 +55,10 @@ export declare class FullFileRenderStrategy extends BaseRenderStrategy {
     reset(): void;
     update(viewportData: ViewportData, viewLineOptions: ViewLineOptions): number;
     draw(pass: GPURenderPassEncoder, viewportData: ViewportData): void;
+    /**
+     * Queue updates that need to happen on the active buffer, not just the cache. This will be
+     * deferred to when the actual cell buffer is changed since the active buffer could be locked by
+     * the GPU which would block the main thread.
+     */
     private _queueBufferUpdate;
 }