@codingame/monaco-vscode-notebook-service-override 20.1.1 → 20.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codingame/monaco-vscode-notebook-service-override",
-  "version": "20.1.1",
+  "version": "20.2.1",
   "private": false,
   "description": "VSCode public API plugged on the monaco editor - notebook service-override",
   "keywords": [],
@@ -15,28 +15,28 @@
   },
   "type": "module",
   "dependencies": {
-    "@codingame/monaco-vscode-0cd5242b-7b61-5f66-ac25-ffa40baf8e8f-common": "20.1.1",
-    "@codingame/monaco-vscode-158b9837-fc78-5d9c-86f5-9134e4358643-common": "20.1.1",
-    "@codingame/monaco-vscode-23aade48-f094-5c08-9555-97fc9cca96c9-common": "20.1.1",
-    "@codingame/monaco-vscode-3109a756-1f83-5d09-945b-9f0fcad928f0-common": "20.1.1",
-    "@codingame/monaco-vscode-501b06ab-3f58-516b-8a1a-c29d375d3da4-common": "20.1.1",
-    "@codingame/monaco-vscode-60014c9d-b815-501d-83a9-4b08725c2ec2-common": "20.1.1",
-    "@codingame/monaco-vscode-622c0cca-d5fa-59b6-b730-0715afcf93ee-common": "20.1.1",
-    "@codingame/monaco-vscode-670aae94-7f88-54d7-90ea-6fcbef423557-common": "20.1.1",
-    "@codingame/monaco-vscode-6f931a91-88ea-5232-897f-a17ec3929ba5-common": "20.1.1",
-    "@codingame/monaco-vscode-6f9bc782-77e0-5716-93bd-b05210c768c5-common": "20.1.1",
-    "@codingame/monaco-vscode-88aa9a78-75f5-5aaa-89e9-bbdd580b3b5c-common": "20.1.1",
-    "@codingame/monaco-vscode-8ccb7637-50ea-5359-97bf-00015d7fe567-common": "20.1.1",
-    "@codingame/monaco-vscode-9ed6fe06-a052-57c2-a234-5d9b94d2e7e0-common": "20.1.1",
-    "@codingame/monaco-vscode-9ee79c1a-3f03-568b-8eac-b02513a98b68-common": "20.1.1",
-    "@codingame/monaco-vscode-a793b3ee-7ba9-5176-a019-30ec806fdd95-common": "20.1.1",
-    "@codingame/monaco-vscode-api": "20.1.1",
-    "@codingame/monaco-vscode-b994942c-360d-5b68-8a33-77d4bde6b714-common": "20.1.1",
-    "@codingame/monaco-vscode-b99aef83-0d60-5e8c-a62e-9908b6256f35-common": "20.1.1",
-    "@codingame/monaco-vscode-caeb744c-8e3f-5c11-80fb-0f057d24d544-common": "20.1.1",
-    "@codingame/monaco-vscode-e28ac690-06d5-5ee9-92d1-02df70296354-common": "20.1.1",
-    "@codingame/monaco-vscode-e4d0fd26-1b26-5583-b3f7-582e08d7b389-common": "20.1.1",
-    "@codingame/monaco-vscode-eda30bac-0984-5b42-9362-c68996b85232-common": "20.1.1",
+    "@codingame/monaco-vscode-0cd5242b-7b61-5f66-ac25-ffa40baf8e8f-common": "20.2.1",
+    "@codingame/monaco-vscode-158b9837-fc78-5d9c-86f5-9134e4358643-common": "20.2.1",
+    "@codingame/monaco-vscode-23aade48-f094-5c08-9555-97fc9cca96c9-common": "20.2.1",
+    "@codingame/monaco-vscode-3109a756-1f83-5d09-945b-9f0fcad928f0-common": "20.2.1",
+    "@codingame/monaco-vscode-501b06ab-3f58-516b-8a1a-c29d375d3da4-common": "20.2.1",
+    "@codingame/monaco-vscode-60014c9d-b815-501d-83a9-4b08725c2ec2-common": "20.2.1",
+    "@codingame/monaco-vscode-622c0cca-d5fa-59b6-b730-0715afcf93ee-common": "20.2.1",
+    "@codingame/monaco-vscode-670aae94-7f88-54d7-90ea-6fcbef423557-common": "20.2.1",
+    "@codingame/monaco-vscode-6f931a91-88ea-5232-897f-a17ec3929ba5-common": "20.2.1",
+    "@codingame/monaco-vscode-6f9bc782-77e0-5716-93bd-b05210c768c5-common": "20.2.1",
+    "@codingame/monaco-vscode-88aa9a78-75f5-5aaa-89e9-bbdd580b3b5c-common": "20.2.1",
+    "@codingame/monaco-vscode-8ccb7637-50ea-5359-97bf-00015d7fe567-common": "20.2.1",
+    "@codingame/monaco-vscode-9ed6fe06-a052-57c2-a234-5d9b94d2e7e0-common": "20.2.1",
+    "@codingame/monaco-vscode-9ee79c1a-3f03-568b-8eac-b02513a98b68-common": "20.2.1",
+    "@codingame/monaco-vscode-a793b3ee-7ba9-5176-a019-30ec806fdd95-common": "20.2.1",
+    "@codingame/monaco-vscode-api": "20.2.1",
+    "@codingame/monaco-vscode-b994942c-360d-5b68-8a33-77d4bde6b714-common": "20.2.1",
+    "@codingame/monaco-vscode-b99aef83-0d60-5e8c-a62e-9908b6256f35-common": "20.2.1",
+    "@codingame/monaco-vscode-caeb744c-8e3f-5c11-80fb-0f057d24d544-common": "20.2.1",
+    "@codingame/monaco-vscode-e28ac690-06d5-5ee9-92d1-02df70296354-common": "20.2.1",
+    "@codingame/monaco-vscode-e4d0fd26-1b26-5583-b3f7-582e08d7b389-common": "20.2.1",
+    "@codingame/monaco-vscode-eda30bac-0984-5b42-9362-c68996b85232-common": "20.2.1",
     "dompurify": "3.2.6",
     "marked": "14.0.0"
   },

package/vscode/src/vs/workbench/contrib/codeEditor/browser/emptyTextEditorHint/emptyTextEditorHint.css

@@ -1,6 +1,12 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
 .monaco-editor .contentWidgets .empty-editor-hint {
 	color: var(--vscode-input-placeholderForeground);
 }
+
 .monaco-editor .contentWidgets .empty-editor-hint a {
 	color: var(--vscode-textLink-foreground)
 }

package/vscode/src/vs/workbench/contrib/notebook/browser/contrib/find/media/notebookFind.css

@@ -1,9 +1,16 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
 .monaco-workbench .notebookOverlay.notebook-editor.find-hide-transition {
 	overflow-y: hidden;
 }
+
 .monaco-workbench .notebookOverlay.notebook-editor.find-show-transition {
 	overflow-y: hidden;
 }
+
 .monaco-workbench .notebookOverlay.notebook-editor .simple-fr-find-part-wrapper .matchesCount {
 	text-align: center;
 	text-overflow: ellipsis;
@@ -12,6 +19,7 @@
 	padding: 0 2px;
 	box-sizing: border-box;
 }
+
 .monaco-workbench .nb-findScope {
 	background-color: var(--vscode-editor-findRangeHighlightBackground);
 }

package/vscode/src/vs/workbench/contrib/notebook/browser/contrib/gettingStarted/notebookGettingStarted.d.ts

@@ -5,6 +5,9 @@ import { IContextKeyService } from "@codingame/monaco-vscode-api/vscode/vs/platf
 import { IStorageService } from "@codingame/monaco-vscode-api/vscode/vs/platform/storage/common/storage.service";
 import { IWorkbenchContribution } from "@codingame/monaco-vscode-api/vscode/vs/workbench/common/contributions";
 import { IEditorService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/editor/common/editorService.service";
+/**
+ * Sets a context key when a notebook has ever been opened by the user
+ */
 export declare class NotebookGettingStarted extends Disposable implements IWorkbenchContribution {
     constructor(_editorService: IEditorService, _storageService: IStorageService, _contextKeyService: IContextKeyService, _commandService: ICommandService, _configurationService: IConfigurationService);
 }

package/vscode/src/vs/workbench/contrib/notebook/browser/contrib/multicursor/notebookMulticursor.d.ts

@@ -61,6 +61,11 @@ export declare class NotebookMultiCursorController extends Disposable implements
     undo(): Promise<void>;
     redo(): Promise<void>;
     private constructCellEditorOptions;
+    /**
+     * Updates the multicursor selection decorations for a specific matched cell
+     *
+     * @param cell -- match object containing the viewmodel + selections
+     */
     private initializeMultiSelectDecorations;
     private updateLazyDecorations;
     private clearDecorations;

package/vscode/src/vs/workbench/contrib/notebook/browser/contrib/outline/notebookOutline.d.ts

@@ -83,7 +83,13 @@ export declare class NotebookCellOutline implements IOutline<OutlineEntry> {
     private checkDelayer;
     constructor(_editor: INotebookEditorPane, _target: OutlineTarget, _themeService: IThemeService, _editorService: IEditorService, _instantiationService: IInstantiationService, _configurationService: IConfigurationService, _languageFeaturesService: ILanguageFeaturesService, _notebookExecutionStateService: INotebookExecutionStateService);
     private initializeOutline;
+    /**
+     * set up the primary data source + three viewing sources for the various outline views
+     */
     private setDataSources;
+    /**
+     * set up the listeners for the outline content, these respond to model changes in the notebook
+     */
     private setModelListeners;
     private computeSymbols;
     doComputeSymbols(cancelToken: CancellationToken): Promise<void>;

package/vscode/src/vs/workbench/contrib/notebook/browser/services/notebookKernelServiceImpl.d.ts

@@ -53,5 +53,8 @@ export declare class NotebookKernelService extends Disposable implements INotebo
     registerNotebookKernelDetectionTask(task: INotebookKernelDetectionTask): IDisposable;
     getKernelDetectionTasks(notebook: INotebookTextModelLike): INotebookKernelDetectionTask[];
     registerKernelSourceActionProvider(viewType: string, provider: IKernelSourceActionProvider): IDisposable;
+    /**
+     * Get kernel source actions from providers
+     */
     getKernelSourceActions2(notebook: INotebookTextModelLike): Promise<INotebookKernelSourceAction[]>;
 }

package/vscode/src/vs/workbench/contrib/notebook/browser/services/notebookRendererMessagingServiceImpl.d.ts

@@ -10,13 +10,20 @@ type MessageToSend = {
 export declare class NotebookRendererMessagingService extends Disposable implements INotebookRendererMessagingService {
     private readonly extensionService;
     _serviceBrand: undefined;
+    /**
+     * Activation promises. Maps renderer IDs to a queue of messages that should
+     * be sent once activation finishes, or undefined if activation is complete.
+     */
     private readonly activations;
     private readonly scopedMessaging;
     private readonly postMessageEmitter;
     readonly onShouldPostMessage: import("@codingame/monaco-vscode-api/vscode/vs/base/common/event").Event<MessageToSend>;
     constructor(extensionService: IExtensionService);
+    /** @inheritdoc */
     receiveMessage(editorId: string | undefined, rendererId: string, message: unknown): Promise<boolean>;
+    /** @inheritdoc */
     prepare(rendererId: string): void;
+    /** @inheritdoc */
     getScoped(editorId: string): IScopedRendererMessaging;
     private postMessage;
 }

package/vscode/src/vs/workbench/contrib/notebook/browser/services/notebookServiceImpl.d.ts

@@ -58,6 +58,7 @@ export declare class NotebookOutputRendererInfoStore {
     get(rendererId: string): NotebookOutputRendererInfo | undefined;
     getAll(): NotebookOutputRendererInfo[];
     add(info: NotebookOutputRendererInfo): void;
+    /** Update and remember the preferred renderer for the given mimetype in this workspace */
     setPreferred(notebookProviderInfo: NotebookProviderInfo, mimeType: string, rendererId: string): void;
     findBestRenderers(notebookProviderInfo: NotebookProviderInfo | undefined, mimeType: string, kernelProvides: readonly string[] | undefined): IOrderedMimeType[];
 }

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

@@ -2,6 +2,9 @@ import { IResourceUndoRedoElement, UndoRedoElementType } from "@codingame/monaco
 import { URI } from "@codingame/monaco-vscode-api/vscode/vs/base/common/uri";
 import { NotebookCellTextModel } from "@codingame/monaco-vscode-e28ac690-06d5-5ee9-92d1-02df70296354-common/vscode/vs/workbench/contrib/notebook/common/model/notebookCellTextModel";
 import { ISelectionState, NotebookCellMetadata } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/notebook/common/notebookCommon";
+/**
+ * It should not modify Undo/Redo stack
+ */
 export interface ITextCellEditingDelegate {
     insertCell?(index: number, cell: NotebookCellTextModel, endSelections?: ISelectionState): void;
     deleteCell?(index: number, endSelections?: ISelectionState): void;

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

@@ -33,7 +33,13 @@ export declare class NotebookTextModel extends Disposable implements INotebookTe
     metadata: NotebookDocumentMetadata;
     transientOptions: TransientOptions;
     private _versionId;
+    /**
+     * This alternative id is only for non-cell-content changes.
+     */
     private _notebookSpecificAlternativeId;
+    /**
+     * Unlike, versionId, this can go down (via undo) or go to previous values (via redo)
+     */
     private _alternativeVersionId;
     private _operationManager;
     private _pauseableEmitter;

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

@@ -5,6 +5,7 @@ declare class DependencyList {
     private readonly value;
     readonly defined: boolean;
     constructor(value: Iterable<string>);
+    /** Gets whether any of the 'available' dependencies match the ones in this list */
     matches(available: ReadonlyArray<string>): boolean;
 }
 export declare class NotebookOutputRendererInfo implements INotebookRendererInfo {

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

@@ -7,6 +7,32 @@ type ICell = {
     getLinesContent(): string[];
     cellKind: CellKind;
 };
+/**
+ * Given a set of modified cells and original cells, this function will attempt to match the modified cells with the original cells.
+ * E.g. Assume you have (original on left and modified on right):
+ * =================
+ * Cell A  | Cell a
+ * Cell B  | Cell b
+ * Cell C  | Cell d
+ * Cell D  | Cell e
+ * =================
+ * Here we know that `Cell C` has been removed and `Cell e` has been added.
+ * The mapping from modified to original will be as follows:
+ * Cell a => Cell A
+ * Cell b => Cell B
+ * Cell d => Cell D
+ * Cell e => <Does not match anything in original, hence a new Cell>
+ * Cell C in original was not matched, hence it was deleted.
+ *
+ * Thus the return value is as follows:
+ * [
+ * { modified: 0, original: 0 },
+ * { modified: 1, original: 1 },
+ * { modified: 2, original: 3 },
+ * { modified: 3, original: -1 },
+ * ]
+ * @returns
+ */
 export declare function matchCellBasedOnSimilarties(modifiedCells: ICell[], originalCells: ICell[]): {
     modified: number;
     original: number;

package/vscode/src/vs/workbench/services/workingCopy/common/abstractFileWorkingCopyManager.d.ts

@@ -6,9 +6,29 @@ import { ILogService } from "@codingame/monaco-vscode-api/vscode/vs/platform/log
 import { IWorkingCopyBackupService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/workingCopy/common/workingCopyBackup.service";
 import { IFileWorkingCopy, IFileWorkingCopyModel } from "@codingame/monaco-vscode-6f931a91-88ea-5232-897f-a17ec3929ba5-common/vscode/vs/workbench/services/workingCopy/common/fileWorkingCopy";
 export interface IBaseFileWorkingCopyManager<M extends IFileWorkingCopyModel, W extends IFileWorkingCopy<M>> extends IDisposable {
+    /**
+     * An event for when a file working copy was created.
+     */
     readonly onDidCreate: Event<W>;
+    /**
+     * Access to all known file working copies within the manager.
+     */
     readonly workingCopies: readonly W[];
+    /**
+     * Returns the file working copy for the provided resource
+     * or `undefined` if none.
+     */
     get(resource: URI): W | undefined;
+    /**
+     * Disposes all working copies of the manager and disposes the manager. This
+     * method is different from `dispose` in that it will unregister any working
+     * copy from the `IWorkingCopyService`. Since this impact things like backups,
+     * the method is `async` because it needs to trigger `save` for any dirty
+     * working copy to preserve the data.
+     *
+     * Callers should make sure to e.g. close any editors associated with the
+     * working copy.
+     */
     destroy(): Promise<void>;
 }
 export declare abstract class BaseFileWorkingCopyManager<M extends IFileWorkingCopyModel, W extends IFileWorkingCopy<M>> extends Disposable implements IBaseFileWorkingCopyManager<M, W> {

package/vscode/src/vs/workbench/services/workingCopy/common/fileWorkingCopyManager.d.ts

@@ -28,16 +28,85 @@ import { IWorkingCopyService } from "@codingame/monaco-vscode-api/vscode/vs/work
 import { IDecorationsService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/decorations/common/decorations.service";
 import { IProgressService } from "@codingame/monaco-vscode-api/vscode/vs/platform/progress/common/progress.service";
 export interface IFileWorkingCopyManager<S extends IStoredFileWorkingCopyModel, U extends IUntitledFileWorkingCopyModel> extends IBaseFileWorkingCopyManager<S | U, IFileWorkingCopy<S | U>> {
+    /**
+     * Provides access to the manager for stored file working copies.
+     */
     readonly stored: IStoredFileWorkingCopyManager<S>;
+    /**
+     * Provides access to the manager for untitled file working copies.
+     */
     readonly untitled: IUntitledFileWorkingCopyManager<U>;
+    /**
+     * Allows to resolve a stored file working copy. If the manager already knows
+     * about a stored file working copy with the same `URI`, it will return that
+     * existing stored file working copy. There will never be more than one
+     * stored file working copy per `URI` until the stored file working copy is
+     * disposed.
+     *
+     * Use the `IStoredFileWorkingCopyResolveOptions.reload` option to control the
+     * behaviour for when a stored file working copy was previously already resolved
+     * with regards to resolving it again from the underlying file resource
+     * or not.
+     *
+     * Note: Callers must `dispose` the working copy when no longer needed.
+     *
+     * @param resource used as unique identifier of the stored file working copy in
+     * case one is already known for this `URI`.
+     * @param options
+     */
     resolve(resource: URI, options?: IStoredFileWorkingCopyManagerResolveOptions): Promise<IStoredFileWorkingCopy<S>>;
+    /**
+     * Create a new untitled file working copy with optional initial contents.
+     *
+     * Note: Callers must `dispose` the working copy when no longer needed.
+     */
     resolve(options?: INewUntitledFileWorkingCopyOptions): Promise<IUntitledFileWorkingCopy<U>>;
+    /**
+     * Create a new untitled file working copy with optional initial contents
+     * and associated resource. The associated resource will be used when
+     * saving and will not require to ask the user for a file path.
+     *
+     * Note: Callers must `dispose` the working copy when no longer needed.
+     */
     resolve(options?: INewUntitledFileWorkingCopyWithAssociatedResourceOptions): Promise<IUntitledFileWorkingCopy<U>>;
+    /**
+     * Creates a new untitled file working copy with optional initial contents
+     * with the provided resource or return an existing untitled file working
+     * copy otherwise.
+     *
+     * Note: Callers must `dispose` the working copy when no longer needed.
+     */
     resolve(options?: INewOrExistingUntitledFileWorkingCopyOptions): Promise<IUntitledFileWorkingCopy<U>>;
+    /**
+     * Implements "Save As" for file based working copies. The API is `URI` based
+     * because it works even without resolved file working copies. If a file working
+     * copy exists for any given `URI`, the implementation will deal with them properly
+     * (e.g. dirty contents of the source will be written to the target and the source
+     * will be reverted).
+     *
+     * Note: it is possible that the returned file working copy has a different `URI`
+     * than the `target` that was passed in. Based on URI identity, the file working
+     * copy may chose to return an existing file working copy with different casing
+     * to respect file systems that are case insensitive.
+     *
+     * Note: Callers must `dispose` the working copy when no longer needed.
+     *
+     * Note: Untitled file working copies are being disposed when saved.
+     *
+     * @param source the source resource to save as
+     * @param target the optional target resource to save to. if not defined, the user
+     * will be asked for input
+     * @returns the target stored working copy that was saved to or `undefined` in case of
+     * cancellation
+     */
     saveAs(source: URI, target: URI, options?: ISaveOptions): Promise<IStoredFileWorkingCopy<S> | undefined>;
     saveAs(source: URI, target: undefined, options?: IFileWorkingCopySaveAsOptions): Promise<IStoredFileWorkingCopy<S> | undefined>;
 }
 export interface IFileWorkingCopySaveAsOptions extends ISaveOptions {
+    /**
+     * Optional target resource to suggest to the user in case
+     * no target resource is provided to save to.
+     */
     suggestedTarget?: URI;
 }
 export declare class FileWorkingCopyManager<S extends IStoredFileWorkingCopyModel, U extends IUntitledFileWorkingCopyModel> extends Disposable implements IFileWorkingCopyManager<S, U> {

package/vscode/src/vs/workbench/services/workingCopy/common/storedFileWorkingCopyManager.d.ts

@@ -16,24 +16,91 @@ import { IFilesConfigurationService } from "@codingame/monaco-vscode-api/vscode/
 import { IWorkingCopyEditorService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/workingCopy/common/workingCopyEditorService.service";
 import { IWorkingCopyService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/workingCopy/common/workingCopyService.service";
 import { IProgressService } from "@codingame/monaco-vscode-api/vscode/vs/platform/progress/common/progress.service";
+/**
+ * The only one that should be dealing with `IStoredFileWorkingCopy` and handle all
+ * operations that are working copy related, such as save/revert, backup
+ * and resolving.
+ */
 export interface IStoredFileWorkingCopyManager<M extends IStoredFileWorkingCopyModel> extends IBaseFileWorkingCopyManager<M, IStoredFileWorkingCopy<M>> {
+    /**
+     * An event for when a stored file working copy was resolved.
+     */
     readonly onDidResolve: Event<IStoredFileWorkingCopy<M>>;
+    /**
+     * An event for when a stored file working copy changed it's dirty state.
+     */
     readonly onDidChangeDirty: Event<IStoredFileWorkingCopy<M>>;
+    /**
+     * An event for when a stored file working copy changed it's readonly state.
+     */
     readonly onDidChangeReadonly: Event<IStoredFileWorkingCopy<M>>;
+    /**
+     * An event for when a stored file working copy changed it's orphaned state.
+     */
     readonly onDidChangeOrphaned: Event<IStoredFileWorkingCopy<M>>;
+    /**
+     * An event for when a stored file working copy failed to save.
+     */
     readonly onDidSaveError: Event<IStoredFileWorkingCopy<M>>;
+    /**
+     * An event for when a stored file working copy successfully saved.
+     */
     readonly onDidSave: Event<IStoredFileWorkingCopySaveEvent<M>>;
+    /**
+     * An event for when a stored file working copy was reverted.
+     */
     readonly onDidRevert: Event<IStoredFileWorkingCopy<M>>;
+    /**
+     * An event for when a stored file working copy is removed from the manager.
+     */
     readonly onDidRemove: Event<URI>;
+    /**
+     * Allows to resolve a stored file working copy. If the manager already knows
+     * about a stored file working copy with the same `URI`, it will return that
+     * existing stored file working copy. There will never be more than one
+     * stored file working copy per `URI` until the stored file working copy is
+     * disposed.
+     *
+     * Use the `IStoredFileWorkingCopyResolveOptions.reload` option to control the
+     * behaviour for when a stored file working copy was previously already resolved
+     * with regards to resolving it again from the underlying file resource
+     * or not.
+     *
+     * Note: Callers must `dispose` the working copy when no longer needed.
+     *
+     * @param resource used as unique identifier of the stored file working copy in
+     * case one is already known for this `URI`.
+     * @param options
+     */
     resolve(resource: URI, options?: IStoredFileWorkingCopyManagerResolveOptions): Promise<IStoredFileWorkingCopy<M>>;
+    /**
+     * Waits for the stored file working copy to be ready to be disposed. There may be
+     * conditions under which the stored file working copy cannot be disposed, e.g. when
+     * it is dirty. Once the promise is settled, it is safe to dispose.
+     */
     canDispose(workingCopy: IStoredFileWorkingCopy<M>): true | Promise<true>;
 }
 export interface IStoredFileWorkingCopySaveEvent<M extends IStoredFileWorkingCopyModel> extends IBaseStoredFileWorkingCopySaveEvent {
+    /**
+     * The stored file working copy that was successfully saved.
+     */
     readonly workingCopy: IStoredFileWorkingCopy<M>;
 }
 export interface IStoredFileWorkingCopyManagerResolveOptions extends IStoredFileWorkingCopyResolveOptions {
+    /**
+     * If the stored file working copy was already resolved before,
+     * allows to trigger a reload of it to fetch the latest contents.
+     */
     readonly reload?: {
+        /**
+         * Controls whether the reload happens in the background
+         * or whether `resolve` will await the reload to happen.
+         */
         readonly async: boolean;
+        /**
+         * Controls whether to force reading the contents from the
+         * underlying resource even if the resource did not change.
+         */
         readonly force?: boolean;
     };
 }

package/vscode/src/vs/workbench/services/workingCopy/common/untitledFileWorkingCopy.d.ts

@@ -9,26 +9,63 @@ import { CancellationToken } from "@codingame/monaco-vscode-api/vscode/vs/base/c
 import { ISaveOptions } from "@codingame/monaco-vscode-api/vscode/vs/workbench/common/editor";
 import { ILogService } from "@codingame/monaco-vscode-api/vscode/vs/platform/log/common/log.service";
 import { IWorkingCopyBackupService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/workingCopy/common/workingCopyBackup.service";
+/**
+ * Untitled file specific working copy model factory.
+ */
 export interface IUntitledFileWorkingCopyModelFactory<M extends IUntitledFileWorkingCopyModel> extends IFileWorkingCopyModelFactory<M> {
 }
+/**
+ * The underlying model of a untitled file working copy provides
+ * some methods for the untitled file working copy to function.
+ * The model is typically only available after the working copy
+ * has been resolved via it's `resolve()` method.
+ */
 export interface IUntitledFileWorkingCopyModel extends IFileWorkingCopyModel {
     readonly onDidChangeContent: Event<IUntitledFileWorkingCopyModelContentChangedEvent>;
 }
 export interface IUntitledFileWorkingCopyModelContentChangedEvent {
+    /**
+     * Flag that indicates that the content change should
+     * clear the dirty/modified flags, e.g. because the contents are
+     * back to being empty or back to an initial state that
+     * should not be considered as modified.
+     */
     readonly isInitial: boolean;
 }
 export interface IUntitledFileWorkingCopy<M extends IUntitledFileWorkingCopyModel> extends IFileWorkingCopy<M> {
+    /**
+     * Whether this untitled file working copy model has an associated file path.
+     */
     readonly hasAssociatedFilePath: boolean;
+    /**
+     * Whether we have a resolved model or not.
+     */
     isResolved(): this is IResolvedUntitledFileWorkingCopy<M>;
 }
 export interface IResolvedUntitledFileWorkingCopy<M extends IUntitledFileWorkingCopyModel> extends IUntitledFileWorkingCopy<M> {
+    /**
+     * A resolved untitled file working copy has a resolved model.
+     */
     readonly model: M;
 }
 export interface IUntitledFileWorkingCopySaveDelegate<M extends IUntitledFileWorkingCopyModel> {
+    /**
+     * A delegate to enable saving of untitled file working copies.
+     */
     (workingCopy: IUntitledFileWorkingCopy<M>, options?: ISaveOptions): Promise<boolean>;
 }
 export interface IUntitledFileWorkingCopyInitialContents {
+    /**
+     * The initial contents of the untitled file working copy.
+     */
     readonly value: VSBufferReadableStream;
+    /**
+     * If not provided, the untitled file working copy will be marked
+     * modified by default given initial contents are provided.
+     *
+     * Note: if the untitled file working copy has an associated path
+     * the modified state will always be set.
+     */
     readonly markModified?: boolean;
 }
 export declare class UntitledFileWorkingCopy<M extends IUntitledFileWorkingCopyModel> extends Disposable implements IUntitledFileWorkingCopy<M> {

package/vscode/src/vs/workbench/services/workingCopy/common/untitledFileWorkingCopyManager.d.ts

@@ -8,22 +8,79 @@ import { IWorkingCopyBackupService } from "@codingame/monaco-vscode-api/vscode/v
 import { IFileService } from "@codingame/monaco-vscode-api/vscode/vs/platform/files/common/files.service";
 import { BaseFileWorkingCopyManager, IBaseFileWorkingCopyManager } from "./abstractFileWorkingCopyManager.js";
 export interface IUntitledFileWorkingCopySaveEvent {
+    /**
+     * The source untitled file working copy that was saved. It is disposed at this point.
+     */
     readonly source: URI;
+    /**
+     * The target file working copy the untitled was saved to. Is never untitled.
+     */
     readonly target: URI;
 }
+/**
+ * The only one that should be dealing with `IUntitledFileWorkingCopy` and
+ * handle all operations that are working copy related, such as save/revert,
+ * backup and resolving.
+ */
 export interface IUntitledFileWorkingCopyManager<M extends IUntitledFileWorkingCopyModel> extends IBaseFileWorkingCopyManager<M, IUntitledFileWorkingCopy<M>> {
+    /**
+     * An event for when an untitled file working copy was saved.
+     * At the point the event fires, the untitled file working copy is
+     * disposed.
+     */
     readonly onDidSave: Event<IUntitledFileWorkingCopySaveEvent>;
+    /**
+     * An event for when a untitled file working copy changed it's dirty state.
+     */
     readonly onDidChangeDirty: Event<IUntitledFileWorkingCopy<M>>;
+    /**
+     * An event for when a untitled file working copy is about to be disposed.
+     */
     readonly onWillDispose: Event<IUntitledFileWorkingCopy<M>>;
+    /**
+     * Create a new untitled file working copy with optional initial contents.
+     *
+     * Note: Callers must `dispose` the working copy when no longer needed.
+     */
     resolve(options?: INewUntitledFileWorkingCopyOptions): Promise<IUntitledFileWorkingCopy<M>>;
+    /**
+     * Create a new untitled file working copy with optional initial contents
+     * and associated resource. The associated resource will be used when
+     * saving and will not require to ask the user for a file path.
+     *
+     * Note: Callers must `dispose` the working copy when no longer needed.
+     */
     resolve(options?: INewUntitledFileWorkingCopyWithAssociatedResourceOptions): Promise<IUntitledFileWorkingCopy<M>>;
+    /**
+     * Creates a new untitled file working copy with optional initial contents
+     * with the provided resource or return an existing untitled file working
+     * copy otherwise.
+     *
+     * Note: Callers must `dispose` the working copy when no longer needed.
+     */
     resolve(options?: INewOrExistingUntitledFileWorkingCopyOptions): Promise<IUntitledFileWorkingCopy<M>>;
+    /**
+     * Internal method: triggers the onDidSave event.
+     */
     notifyDidSave(source: URI, target: URI): void;
 }
 export interface INewUntitledFileWorkingCopyOptions {
+    /**
+     * Initial value of the untitled file working copy
+     * with support to indicate whether this should turn
+     * the working copy dirty or not.
+     */
     contents?: IUntitledFileWorkingCopyInitialContents;
 }
 export interface INewUntitledFileWorkingCopyWithAssociatedResourceOptions extends INewUntitledFileWorkingCopyOptions {
+    /**
+     * Resource components to associate with the untitled file working copy.
+     * When saving, the associated components will be used and the user
+     * is not being asked to provide a file path.
+     *
+     * Note: currently it is not possible to specify the `scheme` to use. The
+     * untitled file working copy will saved to the default local or remote resource.
+     */
     associatedResource: {
         authority?: string;
         path?: string;
@@ -32,7 +89,17 @@ export interface INewUntitledFileWorkingCopyWithAssociatedResourceOptions extend
     };
 }
 export interface INewOrExistingUntitledFileWorkingCopyOptions extends INewUntitledFileWorkingCopyOptions {
+    /**
+     * A resource to identify the untitled file working copy
+     * to create or return if already existing.
+     *
+     * Note: the resource will not be used unless the scheme is `untitled`.
+     */
     untitledResource: URI;
+    /**
+     * A flag that will prevent the working copy from appearing dirty in the UI
+     * and not show a confirmation dialog when closed with unsaved content.
+     */
     isScratchpad?: boolean;
 }
 export declare class UntitledFileWorkingCopyManager<M extends IUntitledFileWorkingCopyModel> extends BaseFileWorkingCopyManager<M, IUntitledFileWorkingCopy<M>> implements IUntitledFileWorkingCopyManager<M> {