@codingame/monaco-vscode-api 20.1.1 → 20.2.1

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

@@ -8,20 +8,104 @@ import { IStoredFileWorkingCopy, IStoredFileWorkingCopyModel } from "@codingame/
 import { IWorkingCopy } from "@codingame/monaco-vscode-caeb744c-8e3f-5c11-80fb-0f057d24d544-common/vscode/vs/workbench/services/workingCopy/common/workingCopy";
 import { WorkingCopyFileEvent, IWorkingCopyFileOperationParticipant, IStoredFileWorkingCopySaveParticipant, IStoredFileWorkingCopySaveParticipantContext, ICreateFileOperation, IFileOperationUndoRedoInfo, ICreateOperation, IMoveOperation, ICopyOperation, IDeleteOperation, WorkingCopyProvider } from "@codingame/monaco-vscode-base-service-override/vscode/vs/workbench/services/workingCopy/common/workingCopyFileService";
 export declare const IWorkingCopyFileService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IWorkingCopyFileService>;
+/**
+* A service that allows to perform file operations with working copy support.
+* Any operation that would leave a stale dirty working copy behind will make
+* sure to revert the working copy first.
+*
+* On top of that events are provided to participate in each state of the
+* operation to perform additional work.
+*/
 export interface IWorkingCopyFileService {
     readonly _serviceBrand: undefined;
+    /**
+    * An event that is fired when a certain working copy IO operation is about to run.
+    *
+    * Participants can join this event with a long running operation to keep some state
+    * before the operation is started, but working copies should not be changed at this
+    * point in time. For that purpose, use the `IWorkingCopyFileOperationParticipant` API.
+    */
     readonly onWillRunWorkingCopyFileOperation: Event<WorkingCopyFileEvent>;
+    /**
+    * An event that is fired after a working copy IO operation has failed.
+    *
+    * Participants can join this event with a long running operation to clean up as needed.
+    */
     readonly onDidFailWorkingCopyFileOperation: Event<WorkingCopyFileEvent>;
+    /**
+    * An event that is fired after a working copy IO operation has been performed.
+    *
+    * Participants can join this event with a long running operation to make changes
+    * after the operation has finished.
+    */
     readonly onDidRunWorkingCopyFileOperation: Event<WorkingCopyFileEvent>;
+    /**
+    * Adds a participant for file operations on working copies.
+    */
     addFileOperationParticipant(participant: IWorkingCopyFileOperationParticipant): IDisposable;
+    /**
+    * Whether save participants are present for stored file working copies.
+    */
     get hasSaveParticipants(): boolean;
+    /**
+    * Adds a participant for save operations on stored file working copies.
+    */
     addSaveParticipant(participant: IStoredFileWorkingCopySaveParticipant): IDisposable;
+    /**
+    * Runs all available save participants for stored file working copies.
+    */
     runSaveParticipants(workingCopy: IStoredFileWorkingCopy<IStoredFileWorkingCopyModel>, context: IStoredFileWorkingCopySaveParticipantContext, progress: IProgress<IProgressStep>, token: CancellationToken): Promise<void>;
+    /**
+    * Will create a resource with the provided optional contents, optionally overwriting any target.
+    *
+    * Working copy owners can listen to the `onWillRunWorkingCopyFileOperation` and
+    * `onDidRunWorkingCopyFileOperation` events to participate.
+    */
     create(operations: ICreateFileOperation[], token: CancellationToken, undoInfo?: IFileOperationUndoRedoInfo): Promise<readonly IFileStatWithMetadata[]>;
+    /**
+    * Will create a folder and any parent folder that needs to be created.
+    *
+    * Working copy owners can listen to the `onWillRunWorkingCopyFileOperation` and
+    * `onDidRunWorkingCopyFileOperation` events to participate.
+    *
+    * Note: events will only be emitted for the provided resource, but not any
+    * parent folders that are being created as part of the operation.
+    */
     createFolder(operations: ICreateOperation[], token: CancellationToken, undoInfo?: IFileOperationUndoRedoInfo): Promise<readonly IFileStatWithMetadata[]>;
+    /**
+    * Will move working copies matching the provided resources and corresponding children
+    * to the target resources using the associated file service for those resources.
+    *
+    * Working copy owners can listen to the `onWillRunWorkingCopyFileOperation` and
+    * `onDidRunWorkingCopyFileOperation` events to participate.
+    */
     move(operations: IMoveOperation[], token: CancellationToken, undoInfo?: IFileOperationUndoRedoInfo): Promise<readonly IFileStatWithMetadata[]>;
+    /**
+    * Will copy working copies matching the provided resources and corresponding children
+    * to the target resources using the associated file service for those resources.
+    *
+    * Working copy owners can listen to the `onWillRunWorkingCopyFileOperation` and
+    * `onDidRunWorkingCopyFileOperation` events to participate.
+    */
     copy(operations: ICopyOperation[], token: CancellationToken, undoInfo?: IFileOperationUndoRedoInfo): Promise<readonly IFileStatWithMetadata[]>;
+    /**
+    * Will delete working copies matching the provided resources and children
+    * using the associated file service for those resources.
+    *
+    * Working copy owners can listen to the `onWillRunWorkingCopyFileOperation` and
+    * `onDidRunWorkingCopyFileOperation` events to participate.
+    */
     delete(operations: IDeleteOperation[], token: CancellationToken, undoInfo?: IFileOperationUndoRedoInfo): Promise<void>;
+    /**
+    * Register a new provider for working copies based on a resource.
+    *
+    * @return a disposable that unregisters the provider.
+    */
     registerWorkingCopyProvider(provider: WorkingCopyProvider): IDisposable;
+    /**
+    * Will return all working copies that are dirty matching the provided resource.
+    * If the resource is a folder and the scheme supports file operations, a working
+    * copy that is dirty and is a child of that folder will also be returned.
+    */
     getDirty(resource: URI): readonly IWorkingCopy[];
 }

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

@@ -6,19 +6,62 @@ import { IWorkingCopyHistoryEvent, IWorkingCopyHistoryEntryDescriptor, IWorkingC
 export declare const IWorkingCopyHistoryService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IWorkingCopyHistoryService>;
 export interface IWorkingCopyHistoryService {
     readonly _serviceBrand: undefined;
+    /**
+    * An event when an entry is added to the history.
+    */
     onDidAddEntry: Event<IWorkingCopyHistoryEvent>;
+    /**
+    * An event when an entry is changed in the history.
+    */
     onDidChangeEntry: Event<IWorkingCopyHistoryEvent>;
+    /**
+    * An event when an entry is replaced in the history.
+    */
     onDidReplaceEntry: Event<IWorkingCopyHistoryEvent>;
+    /**
+    * An event when an entry is removed from the history.
+    */
     onDidRemoveEntry: Event<IWorkingCopyHistoryEvent>;
+    /**
+    * An event when entries are moved in history.
+    */
     onDidMoveEntries: Event<void>;
+    /**
+    * An event when all entries are removed from the history.
+    */
     onDidRemoveEntries: Event<void>;
+    /**
+    * Adds a new entry to the history for the given working copy
+    * with an optional associated descriptor.
+    */
     addEntry(descriptor: IWorkingCopyHistoryEntryDescriptor, token: CancellationToken): Promise<IWorkingCopyHistoryEntry | undefined>;
+    /**
+    * Updates an entry in the local history if found.
+    */
     updateEntry(entry: IWorkingCopyHistoryEntry, properties: {
         source: SaveSource;
     }, token: CancellationToken): Promise<void>;
+    /**
+    * Removes an entry from the local history if found.
+    */
     removeEntry(entry: IWorkingCopyHistoryEntry, token: CancellationToken): Promise<boolean>;
+    /**
+    * Moves entries that either match the `source` or are a child
+    * of `source` to the `target`.
+    *
+    * @returns a list of resources for entries that have moved.
+    */
     moveEntries(source: URI, target: URI): Promise<URI[]>;
+    /**
+    * Gets all history entries for the provided resource.
+    */
     getEntries(resource: URI, token: CancellationToken): Promise<readonly IWorkingCopyHistoryEntry[]>;
+    /**
+    * Returns all resources for which history entries exist.
+    */
     getAll(token: CancellationToken): Promise<readonly URI[]>;
+    /**
+    * Removes all entries from all of local history.
+    */
     removeAll(token: CancellationToken): Promise<void>;
 }

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

@@ -6,21 +6,84 @@ import { IWorkingCopySaveEvent } from "@codingame/monaco-vscode-working-copy-ser
 export declare const IWorkingCopyService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IWorkingCopyService>;
 export interface IWorkingCopyService {
     readonly _serviceBrand: undefined;
+    /**
+    * An event for when a working copy was registered.
+    */
     readonly onDidRegister: Event<IWorkingCopy>;
+    /**
+    * An event for when a working copy was unregistered.
+    */
     readonly onDidUnregister: Event<IWorkingCopy>;
+    /**
+    * An event for when a working copy dirty state changed.
+    */
     readonly onDidChangeDirty: Event<IWorkingCopy>;
+    /**
+    * An event for when a working copy's content changed.
+    */
     readonly onDidChangeContent: Event<IWorkingCopy>;
+    /**
+    * An event for when a working copy was saved.
+    */
     readonly onDidSave: Event<IWorkingCopySaveEvent>;
+    /**
+    * The number of dirty working copies that are registered.
+    */
     readonly dirtyCount: number;
+    /**
+    * All dirty working copies that are registered.
+    */
     readonly dirtyWorkingCopies: readonly IWorkingCopy[];
+    /**
+    * The number of modified working copies that are registered,
+    * including scratchpads, which are never dirty.
+    */
     readonly modifiedCount: number;
+    /**
+    * All working copies with unsaved changes,
+    * including scratchpads, which are never dirty.
+    */
     readonly modifiedWorkingCopies: readonly IWorkingCopy[];
+    /**
+    * Whether there is any registered working copy that is dirty.
+    */
     readonly hasDirty: boolean;
+    /**
+    * Figure out if working copies with the given
+    * resource are dirty or not.
+    *
+    * @param resource the URI of the working copy
+    * @param typeId optional type identifier to only
+    * consider working copies of that type.
+    */
     isDirty(resource: URI, typeId?: string): boolean;
+    /**
+    * All working copies that are registered.
+    */
     readonly workingCopies: readonly IWorkingCopy[];
+    /**
+    * Register a new working copy with the service. This method will
+    * throw if you try to register a working copy on a resource that
+    * has already been registered.
+    *
+    * Overall there can only ever be 1 working copy with the same
+    * resource.
+    */
     registerWorkingCopy(workingCopy: IWorkingCopy): IDisposable;
+    /**
+    * Whether a working copy with the given resource or identifier
+    * exists.
+    */
     has(identifier: IWorkingCopyIdentifier): boolean;
     has(resource: URI): boolean;
+    /**
+    * Returns a working copy with the given identifier or `undefined`
+    * if no such working copy exists.
+    */
     get(identifier: IWorkingCopyIdentifier): IWorkingCopy | undefined;
+    /**
+    * Returns all working copies with the given resource or `undefined`
+    * if no such working copy exists.
+    */
     getAll(resource: URI): readonly IWorkingCopy[] | undefined;
 }

package/vscode/src/vs/workbench/services/workspaces/common/workspaceEditing.service.d.ts

@@ -4,12 +4,40 @@ import { IWorkspaceFolderCreationData } from "@codingame/monaco-vscode-158b9837-
 export declare const IWorkspaceEditingService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IWorkspaceEditingService>;
 export interface IWorkspaceEditingService {
     readonly _serviceBrand: undefined;
+    /**
+    * Add folders to the existing workspace.
+    * When `donotNotifyError` is `true`, error will be bubbled up otherwise, the service handles the error with proper message and action
+    */
     addFolders(folders: IWorkspaceFolderCreationData[], donotNotifyError?: boolean): Promise<void>;
+    /**
+    * Remove folders from the existing workspace
+    * When `donotNotifyError` is `true`, error will be bubbled up otherwise, the service handles the error with proper message and action
+    */
     removeFolders(folders: URI[], donotNotifyError?: boolean): Promise<void>;
+    /**
+    * Allows to add and remove folders to the existing workspace at once.
+    * When `donotNotifyError` is `true`, error will be bubbled up otherwise, the service handles the error with proper message and action
+    */
     updateFolders(index: number, deleteCount?: number, foldersToAdd?: IWorkspaceFolderCreationData[], donotNotifyError?: boolean): Promise<void>;
+    /**
+    * Enters the workspace with the provided path.
+    */
     enterWorkspace(path: URI): Promise<void>;
+    /**
+    * Creates a new workspace with the provided folders and opens it. if path is provided
+    * the workspace will be saved into that location.
+    */
     createAndEnterWorkspace(folders: IWorkspaceFolderCreationData[], path?: URI): Promise<void>;
+    /**
+    * Saves the current workspace to the provided path and opens it. requires a workspace to be opened.
+    */
     saveAndEnterWorkspace(path: URI): Promise<void>;
+    /**
+    * Copies current workspace settings to the target workspace.
+    */
     copyWorkspaceSettings(toWorkspace: IWorkspaceIdentifier): Promise<void>;
+    /**
+    * Picks a new workspace path
+    */
     pickNewWorkspacePath(): Promise<URI | undefined>;
 }