@codingame/monaco-vscode-api 20.1.1 → 20.2.1

package/vscode/src/vs/workbench/contrib/notebook/common/notebookCommon.d.ts

@@ -38,6 +38,12 @@ export declare enum CellKind {
 }
 export declare const NOTEBOOK_DISPLAY_ORDER: readonly string[];
 export declare const ACCESSIBLE_NOTEBOOK_DISPLAY_ORDER: readonly string[];
+/**
+ * A mapping of extension IDs who contain renderers, to notebook ids who they
+ * should be treated as the same in the renderer selection logic. This is used
+ * to prefer the 1st party Jupyter renderers even though they're in a separate
+ * extension, for instance. See #136247.
+ */
 export declare const RENDERER_EQUIVALENT_EXTENSIONS: ReadonlyMap<string, ReadonlySet<string>>;
 export declare const RENDERER_NOT_AVAILABLE = "_notAvailable";
 export type ContributedNotebookRendererEntrypoint = string | {
@@ -65,9 +71,17 @@ export interface INotebookCellPreviousExecutionResult {
     duration?: number;
 }
 export interface NotebookCellMetadata {
+    /**
+     * custom metadata
+     */
     [key: string]: unknown;
 }
 export interface NotebookCellInternalMetadata {
+    /**
+     * Used only for diffing of Notebooks.
+     * This is not persisted and generally useful only when diffing two notebooks.
+     * Useful only after we've manually matched a few cells together so we know which cells are matching.
+     */
     internalId?: string;
     executionId?: string;
     executionOrder?: number;
@@ -104,12 +118,23 @@ export interface TransientOptions {
     readonly transientDocumentMetadata: TransientDocumentMetadata;
     readonly cellContentMetadata: CellContentMetadata;
 }
+/** Note: enum values are used for sorting */
 export declare enum NotebookRendererMatch {
+    /** Renderer has a hard dependency on an available kernel */
     WithHardKernelDependency = 0,
+    /** Renderer works better with an available kernel */
     WithOptionalKernelDependency = 1,
+    /** Renderer is kernel-agnostic */
     Pure = 2,
+    /** Renderer is for a different mimeType or has a hard dependency which is unsatisfied */
     Never = 3
 }
+/**
+ * Renderer messaging requirement. While this allows for 'optional' messaging,
+ * VS Code effectively treats it the same as true right now. "Partial
+ * activation" of extensions is a very tricky problem, which could allow
+ * solving this. But for now, optional is mostly only honored for aznb.
+ */
 export declare enum RendererMessagingSpec {
     Always = "always",
     Never = "never",
@@ -156,6 +181,9 @@ export interface ICellOutput {
     outputs: IOutputItemDto[];
     metadata?: Record<string, any>;
     outputId: string;
+    /**
+     * Alternative output id that's reused when the output is updated.
+     */
     alternativeOutputId: string;
     onDidChangeData: Event<void>;
     replaceData(items: IOutputDto): void;
@@ -169,10 +197,19 @@ export interface CellInternalMetadataChangedEvent {
     readonly lastRunSuccessChanged?: boolean;
 }
 export interface INotebookDocumentMetadataTextModel {
+    /**
+     * Notebook Metadata Uri.
+     */
     readonly uri: URI;
+    /**
+     * Triggered when the Notebook Metadata changes.
+     */
     readonly onDidChange: Event<void>;
     readonly metadata: Readonly<NotebookDocumentMetadata>;
     readonly textBuffer: IReadonlyTextBuffer;
+    /**
+     * Text representation of the Notebook Metadata
+     */
     getValue(): string;
     getHash(): string;
 }
@@ -471,7 +508,15 @@ export declare namespace CellUri {
         notebook: URI;
         handle: number;
     } | undefined;
+    /**
+     * Generates a URI for a cell output in a notebook using the output ID.
+     * Used when URI should be opened as text in the editor.
+     */
     function generateCellOutputUriWithId(notebook: URI, outputId?: string): URI;
+    /**
+     * Generates a URI for a cell output in a notebook using the output index.
+     * Used when URI should be opened in notebook editor.
+     */
     function generateCellOutputUriWithIndex(notebook: URI, cellUri: URI, outputIndex: number): URI;
     function generateOutputEditorUri(notebook: URI, cellId: string, cellIndex: number, outputId: string, outputIndex: number): URI;
     function parseCellOutputUri(uri: URI): {
@@ -493,8 +538,18 @@ export declare class MimeTypeDisplayOrder {
     private readonly defaultOrder;
     private readonly order;
     constructor(initialValue?: readonly string[], defaultOrder?: readonly string[]);
+    /**
+     * Returns a sorted array of the input mimetypes.
+     */
     sort(mimetypes: Iterable<string>): string[];
+    /**
+     * Records that the user selected the given mimetype over the other
+     * possible mimetypes, prioritizing it for future reference.
+     */
     prioritize(chosenMimetype: string, otherMimetypes: readonly string[]): void;
+    /**
+     * Gets an array of in-order mimetype preferences.
+     */
     toArray(): string[];
     private findIndex;
 }
@@ -505,7 +560,14 @@ export interface ICellEditorViewState {
 export declare const NOTEBOOK_EDITOR_CURSOR_BOUNDARY: RawContextKey<"top" | "none" | "bottom" | "both">;
 export declare const NOTEBOOK_EDITOR_CURSOR_LINE_BOUNDARY: RawContextKey<"start" | "end" | "none" | "both">;
 export interface INotebookLoadOptions {
+    /**
+     * Go to disk bypassing any cache of the model if any.
+     */
     forceReadFromFile?: boolean;
+    /**
+     * If provided, the size of the file will be checked against the limits
+     * and an error will be thrown if any limit is exceeded.
+     */
     readonly limits?: IFileReadLimits;
 }
 export type NotebookEditorModelCreationOptions = {
@@ -698,7 +760,16 @@ export interface NotebookExtensionDescription {
     readonly id: ExtensionIdentifier;
     readonly location: UriComponents | undefined;
 }
+/**
+ * Whether the provided mime type is a text stream like `stdout`, `stderr`.
+ */
 export declare function isTextStreamMime(mimeType: string): boolean;
+/**
+ * Given a stream of individual stdout outputs, this function will return the compressed lines, escaping some of the common terminal escape codes.
+ * E.g. some terminal escape codes would result in the previous line getting cleared, such if we had 3 lines and
+ * last line contained such a code, then the result string would be just the first two lines.
+ * @returns a single VSBuffer with the concatenated and compressed data, and whether any compression was done.
+ */
 export declare function compressOutputItemStreams(outputs: Uint8Array[]): {
     data: VSBuffer;
     didCompression: boolean;

package/vscode/src/vs/workbench/contrib/notebook/common/notebookEditorModelResolverService.d.ts

@@ -1,9 +1,28 @@
 import { URI } from "../../../../base/common/uri.js";
 import { IWaitUntil } from "../../../../base/common/event.js";
+/**
+ * A notebook file can only be opened ONCE per notebook type.
+ * This event fires when a file is already open as type A
+ * and there is request to open it as type B. Listeners must
+ * do cleanup (close editor, release references) or the request fails
+ */
 export interface INotebookConflictEvent extends IWaitUntil {
     resource: URI;
     viewType: string;
 }
 export interface IUntitledNotebookResource {
+    /**
+     * Depending on the value of `untitledResource` will
+     * resolve a untitled notebook that:
+     * - gets a unique name if `undefined` (e.g. `Untitled-1')
+     * - uses the resource directly if the scheme is `untitled:`
+     * - converts any other resource scheme to `untitled:` and will
+     *   assume an associated file path
+     *
+     * Untitled notebook editors with associated path behave slightly
+     * different from other untitled editors:
+     * - they are dirty right when opening
+     * - they will not ask for a file path when saving but use the associated path
+     */
     untitledResource: URI | undefined;
 }

package/vscode/src/vs/workbench/contrib/notebook/common/notebookKernelService.service.d.ts

@@ -14,9 +14,22 @@ export interface INotebookKernelService {
     readonly onDidNotebookVariablesUpdate: Event<URI>;
     registerKernel(kernel: INotebookKernel): IDisposable;
     getMatchingKernel(notebook: INotebookTextModelLike): INotebookKernelMatchResult;
+    /**
+    * Returns the selected or only available kernel.
+    */
     getSelectedOrSuggestedKernel(notebook: INotebookTextModelLike): INotebookKernel | undefined;
+    /**
+    * Bind a notebook document to a kernel. A notebook is only bound to one kernel
+    * but a kernel can be bound to many notebooks (depending on its configuration)
+    */
     selectKernelForNotebook(kernel: INotebookKernel, notebook: INotebookTextModelLike): void;
+    /**
+    * Set the kernel that a notebook should use when it starts up
+    */
     preselectKernelForNotebook(kernel: INotebookKernel, notebook: INotebookTextModelLike): void;
+    /**
+    * Set a perference of a kernel for a certain notebook. Higher values win, `undefined` removes the preference
+    */
     updateKernelNotebookAffinity(kernel: INotebookKernel, notebook: URI, preference: number | undefined): void;
     readonly onDidChangeKernelDetectionTasks: Event<string>;
     registerNotebookKernelDetectionTask(task: INotebookKernelDetectionTask): IDisposable;

package/vscode/src/vs/workbench/contrib/notebook/common/notebookRendererMessagingService.d.ts

@@ -1,5 +1,12 @@
 import { IDisposable } from "../../../../base/common/lifecycle.js";
 export interface IScopedRendererMessaging extends IDisposable {
+    /**
+     * Method called when a message is received. Should return a boolean
+     * indicating whether a renderer received it.
+     */
     receiveMessageHandler?: (rendererId: string, message: unknown) => Promise<boolean>;
+    /**
+     * Sends a message to an extension from a renderer.
+     */
     postMessage(rendererId: string, message: unknown): void;
 }

package/vscode/src/vs/workbench/contrib/notebook/common/notebookRendererMessagingService.service.d.ts

@@ -3,12 +3,24 @@ import { IScopedRendererMessaging } from "./notebookRendererMessagingService.js"
 export declare const INotebookRendererMessagingService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<INotebookRendererMessagingService>;
 export interface INotebookRendererMessagingService {
     readonly _serviceBrand: undefined;
+    /**
+    * Event that fires when a message should be posted to extension hosts.
+    */
     onShouldPostMessage: Event<{
         editorId: string;
         rendererId: string;
         message: unknown;
     }>;
+    /**
+    * Prepares messaging for the given renderer ID.
+    */
     prepare(rendererId: string): void;
+    /**
+    * Gets messaging scoped for a specific editor.
+    */
     getScoped(editorId: string): IScopedRendererMessaging;
+    /**
+    * Called when the main thread gets a message for a renderer.
+    */
     receiveMessage(editorId: string | undefined, rendererId: string, message: unknown): Promise<boolean>;
 }

package/vscode/src/vs/workbench/contrib/notebook/common/notebookService.service.d.ts

@@ -29,6 +29,7 @@ export interface INotebookService {
     getRendererInfo(id: string): INotebookRendererInfo | undefined;
     getRenderers(): INotebookRendererInfo[];
     getStaticPreloads(viewType: string): Iterable<INotebookStaticPreloadInfo>;
+    /** Updates the preferred renderer for the given mimetype in the workspace. */
     updateMimePreferredRenderer(viewType: string, mimeType: string, rendererId: string, otherMimetypes: readonly string[]): void;
     saveMimeDisplayOrder(target: ConfigurationTarget): void;
     createNotebookTextModel(viewType: string, uri: URI, stream?: VSBufferReadableStream): Promise<NotebookTextModel>;
@@ -37,6 +38,7 @@ export interface INotebookService {
     getNotebookTextModel(uri: URI): NotebookTextModel | undefined;
     getNotebookTextModels(): Iterable<NotebookTextModel>;
     listNotebookDocuments(): readonly NotebookTextModel[];
+    /**	Register a notebook type that we will handle. The notebook editor will be registered for notebook types contributed by extensions */
     registerContributedNotebookType(viewType: string, data: INotebookContributionData): IDisposable;
     getContributedNotebookType(viewType: string): NotebookProviderInfo | undefined;
     getContributedNotebookTypes(resource?: URI): readonly NotebookProviderInfo[];

package/vscode/src/vs/workbench/contrib/scm/browser/quickDiffModel.service.d.ts

@@ -4,5 +4,11 @@ import { QuickDiffModelOptions, QuickDiffModel } from "@codingame/monaco-vscode-
 export declare const IQuickDiffModelService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IQuickDiffModelService>;
 export interface IQuickDiffModelService {
     _serviceBrand: undefined;
+    /**
+    * Returns `undefined` if the editor model is not resolved.
+    * Model refrence has to be disposed once not needed anymore.
+    * @param resource
+    * @param options
+    */
     createQuickDiffModelReference(resource: URI, options?: QuickDiffModelOptions): IReference<QuickDiffModel> | undefined;
 }

package/vscode/src/vs/workbench/contrib/scm/common/scm.service.d.ts

@@ -27,6 +27,9 @@ export interface ISCMViewService {
     readonly focusedRepository: ISCMRepository | undefined;
     readonly onDidFocusRepository: Event<ISCMRepository | undefined>;
     focus(repository: ISCMRepository): void;
+    /**
+    * Focused repository or the repository for the active editor
+    */
     readonly activeRepository: IObservable<ISCMRepository | undefined>;
     pinActiveRepository(repository: ISCMRepository | undefined): void;
 }

package/vscode/src/vs/workbench/contrib/search/browser/replace.service.d.ts

@@ -3,8 +3,22 @@ import { ISearchTreeMatch, ISearchTreeFileMatch, FileMatchOrMatch } from "@codin
 export declare const IReplaceService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IReplaceService>;
 export interface IReplaceService {
     readonly _serviceBrand: undefined;
+    /**
+    * Replaces the given match in the file that match belongs to
+    */
     replace(match: ISearchTreeMatch): Promise<any>;
+    /**
+    *	Replace all the matches from the given file matches in the files
+    *  You can also pass the progress runner to update the progress of replacing.
+    */
     replace(files: ISearchTreeFileMatch[], progress?: IProgress<IProgressStep>): Promise<any>;
+    /**
+    * Opens the replace preview for given file match or match
+    */
     openReplacePreview(element: FileMatchOrMatch, preserveFocus?: boolean, sideBySide?: boolean, pinned?: boolean): Promise<any>;
+    /**
+    * Update the replace preview for the given file.
+    * If `override` is `true`, then replace preview is constructed from source model
+    */
     updateReplacePreview(file: ISearchTreeFileMatch, override?: boolean): Promise<void>;
 }

package/vscode/src/vs/workbench/contrib/speech/common/speechService.service.d.ts

@@ -11,13 +11,27 @@ export interface ISpeechService {
     readonly onDidStartSpeechToTextSession: Event<void>;
     readonly onDidEndSpeechToTextSession: Event<void>;
     readonly hasActiveSpeechToTextSession: boolean;
+    /**
+    * Starts to transcribe speech from the default microphone. The returned
+    * session object provides an event to subscribe for transcribed text.
+    */
     createSpeechToTextSession(token: CancellationToken, context?: string): Promise<ISpeechToTextSession>;
     readonly onDidStartTextToSpeechSession: Event<void>;
     readonly onDidEndTextToSpeechSession: Event<void>;
     readonly hasActiveTextToSpeechSession: boolean;
+    /**
+    * Creates a synthesizer to synthesize speech from text. The returned
+    * session object provides a method to synthesize text and listen for
+    * events.
+    */
     createTextToSpeechSession(token: CancellationToken, context?: string): Promise<ITextToSpeechSession>;
     readonly onDidStartKeywordRecognition: Event<void>;
     readonly onDidEndKeywordRecognition: Event<void>;
     readonly hasActiveKeywordRecognition: boolean;
+    /**
+    * Starts to recognize a keyword from the default microphone. The returned
+    * status indicates if the keyword was recognized or if the session was
+    * stopped.
+    */
     recognizeKeyword(token: CancellationToken): Promise<KeywordRecognitionStatus>;
 }

package/vscode/src/vs/workbench/contrib/tags/common/workspaceTags.service.d.ts

@@ -5,6 +5,10 @@ export declare const IWorkspaceTagsService: import("../../../../platform/instant
 export interface IWorkspaceTagsService {
     readonly _serviceBrand: undefined;
     getTags(): Promise<Tags>;
+    /**
+    * Returns an id for the workspace, different from the id returned by the context service. A hash based
+    * on the folder uri or workspace configuration, not time-based, and undefined for empty workspaces.
+    */
     getTelemetryWorkspaceId(workspace: IWorkspace, state: WorkbenchState): Promise<string | undefined>;
     getHashedRemotesFromUri(workspaceUri: URI, stripEndingDotGit?: boolean): Promise<string[]>;
 }

package/vscode/src/vs/workbench/contrib/tasks/common/taskService.service.d.ts

@@ -10,6 +10,7 @@ export declare const ITaskService: import("../../../../platform/instantiation/co
 export interface ITaskService {
     readonly _serviceBrand: undefined;
     onDidStateChange: Event<ITaskEvent>;
+    /** Fired when task providers are registered or unregistered */
     onDidChangeTaskProviders: Event<void>;
     isReconnected: boolean;
     onDidReconnectToTasks: Event<void>;
@@ -22,12 +23,19 @@ export interface ITaskService {
     terminate(task: Task): Promise<ITaskTerminateResponse>;
     tasks(filter?: ITaskFilter): Promise<Task[]>;
     rerun(terminalInstanceId: number): void;
+    /**
+    * Gets tasks currently known to the task system. Unlike {@link tasks},
+    * this does not activate extensions or prompt for workspace trust.
+    */
     getKnownTasks(filter?: ITaskFilter): Promise<Task[]>;
     taskTypes(): string[];
     getWorkspaceTasks(runSource?: TaskRunSource): Promise<Map<string, IWorkspaceFolderTaskResult>>;
     getSavedTasks(type: "persistent" | "historical"): Promise<(Task | ConfiguringTask)[]>;
     removeRecentlyUsedTask(taskRecentlyUsedKey: string): void;
     getTerminalForTask(task: Task): URI | undefined;
+    /**
+    * @param alias The task's name, label or defined identifier.
+    */
     getTask(workspaceFolder: IWorkspace | IWorkspaceFolder | string, alias: string | ITaskIdentifier, compareId?: boolean): Promise<Task | undefined>;
     tryResolveTask(configuringTask: ConfiguringTask): Promise<Task | undefined>;
     createSorter(): TaskSorter;