@codingame/monaco-vscode-api 20.1.1 → 20.2.1

package/vscode/src/vs/platform/quickinput/common/quickInput.service.d.ts

@@ -5,10 +5,26 @@ import { IQuickInputButton, IQuickPickItem, QuickPickInput, IPickOptions, Omit,
 export declare const IQuickInputService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IQuickInputService>;
 export interface IQuickInputService {
     readonly _serviceBrand: undefined;
+    /**
+    * Provides access to the back button in quick input.
+    */
     readonly backButton: IQuickInputButton;
+    /**
+    * Provides access to the quick access providers.
+    */
     readonly quickAccess: IQuickAccessController;
+    /**
+    * Allows to register on the event that quick input is showing.
+    */
     readonly onShow: Event<void>;
+    /**
+    * Allows to register on the event that quick input is hiding.
+    */
     readonly onHide: Event<void>;
+    /**
+    * Opens the quick input box for selecting items and returns a promise
+    * with the user selected item(s) if any.
+    */
     pick<T extends IQuickPickItem>(picks: Promise<QuickPickInput<T>[]> | QuickPickInput<T>[], options?: IPickOptions<T> & {
         canPickMany: true;
     }, token?: CancellationToken): Promise<T[] | undefined>;
@@ -16,7 +32,13 @@ export interface IQuickInputService {
         canPickMany: false;
     }, token?: CancellationToken): Promise<T | undefined>;
     pick<T extends IQuickPickItem>(picks: Promise<QuickPickInput<T>[]> | QuickPickInput<T>[], options?: Omit<IPickOptions<T>, "canPickMany">, token?: CancellationToken): Promise<T | undefined>;
+    /**
+    * Opens the quick input box for text input and returns a promise with the user typed value if any.
+    */
     input(options?: IInputOptions, token?: CancellationToken): Promise<string | undefined>;
+    /**
+    * Provides raw access to the quick pick controller.
+    */
     createQuickPick<T extends IQuickPickItem>(options: {
         useSeparators: true;
     }): IQuickPick<T, {
@@ -27,17 +49,58 @@ export interface IQuickInputService {
     }): IQuickPick<T, {
         useSeparators: false;
     }>;
+    /**
+    * Provides raw access to the input box controller.
+    */
     createInputBox(): IInputBox;
+    /**
+    * Provides raw access to the quick widget controller.
+    */
     createQuickWidget(): IQuickWidget;
+    /**
+    * Provides raw access to the quick tree controller.
+    * @template T The type of items in the quick tree.
+    */
     createQuickTree<T extends IQuickTreeItem>(): IQuickTree<T>;
+    /**
+    * Moves focus into quick input.
+    */
     focus(): void;
+    /**
+    * Toggle the checked state of the selected item.
+    */
     toggle(): void;
+    /**
+    * Navigate inside the opened quick input list.
+    */
     navigate(next: boolean, quickNavigate?: IQuickNavigateConfiguration): void;
+    /**
+    * Navigate back in a multi-step quick input.
+    */
     back(): Promise<void>;
+    /**
+    * Accept the selected item.
+    *
+    * @param keyMods allows to override the state of key
+    * modifiers that should be present when invoking.
+    */
     accept(keyMods?: IKeyMods): Promise<void>;
+    /**
+    * Cancels quick input and closes it.
+    */
     cancel(): Promise<void>;
+    /**
+    * Toggles hover for the current quick input item
+    */
     toggleHover(): void;
+    /**
+    * The current quick pick that is visible. Undefined if none is open.
+    */
     currentQuickInput: IQuickInput | undefined;
+    /**
+    * Set the alignment of the quick input.
+    * @param alignment either a preset or a custom alignment
+    */
     setAlignment(alignment: "top" | "center" | {
         top: number;
         left: number;

package/vscode/src/vs/platform/registry/common/platform.d.ts

@@ -1,6 +1,20 @@
 export interface IRegistry {
+    /**
+     * Adds the extension functions and properties defined by data to the
+     * platform. The provided id must be unique.
+     * @param id a unique identifier
+     * @param data a contribution
+     */
     add(id: string, data: any): void;
+    /**
+     * Returns true iff there is an extension with the provided id.
+     * @param id an extension identifier
+     */
     knows(id: string): boolean;
+    /**
+     * Returns the extension functions and properties defined by the specified key or null.
+     * @param id an extension identifier
+     */
     as<T>(id: string): T;
 }
 export declare const Registry: IRegistry;

package/vscode/src/vs/platform/remote/common/remoteAuthorityResolver.service.d.ts

@@ -7,6 +7,13 @@ export interface IRemoteAuthorityResolverService {
     readonly onDidChangeConnectionData: Event<void>;
     resolveAuthority(authority: string): Promise<ResolverResult>;
     getConnectionData(authority: string): IRemoteConnectionData | null;
+    /**
+    * Get the canonical URI for a `vscode-remote://` URI.
+    *
+    * **NOTE**: This can throw e.g. in cases where there is no resolver installed for the specific remote authority.
+    *
+    * @param uri The `vscode-remote://` URI
+    */
     getCanonicalURI(uri: URI): Promise<URI>;
     _clearResolvedAuthority(authority: string): void;
     _setResolvedAuthority(resolvedAuthority: ResolvedAuthority, resolvedOptions?: ResolvedOptions): void;

package/vscode/src/vs/platform/remote/common/remoteExtensionsScanner.service.d.ts

@@ -3,6 +3,9 @@ import { IExtensionDescription } from "../../extensions/common/extensions.js";
 export declare const IRemoteExtensionsScannerService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IRemoteExtensionsScannerService>;
 export interface IRemoteExtensionsScannerService {
     readonly _serviceBrand: undefined;
+    /**
+    * Returns a promise that resolves to an array of extension identifiers that failed to install
+    */
     whenExtensionsReady(): Promise<InstallExtensionSummary>;
     scanExtensions(): Promise<IExtensionDescription[]>;
 }

package/vscode/src/vs/platform/remote/common/remoteSocketFactoryService.service.d.ts

@@ -5,6 +5,12 @@ import { ISocketFactory } from "@codingame/monaco-vscode-remote-agent-service-ov
 export declare const IRemoteSocketFactoryService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IRemoteSocketFactoryService>;
 export interface IRemoteSocketFactoryService {
     readonly _serviceBrand: undefined;
+    /**
+    * Register a socket factory for the given message passing type
+    * @param type passing type to register for
+    * @param factory function that returns the socket factory, or undefined if
+    * it can't handle the data.
+    */
     register<T extends RemoteConnectionType>(type: T, factory: ISocketFactory<T>): IDisposable;
     connect(connectTo: RemoteConnection, path: string, query: string, debugLabel: string): Promise<ISocket>;
 }

package/vscode/src/vs/platform/storage/common/storage.d.ts

@@ -7,7 +7,13 @@ import { IStorageService } from "./storage.service.js";
 export declare const IS_NEW_KEY = "__$__isNewStorageMarker";
 export declare const TARGET_KEY = "__$__targetStorageMarker";
 export declare enum WillSaveStateReason {
+    /**
+     * No specific reason to save state.
+     */
     NONE = 0,
+    /**
+     * A hint that the workbench is about to shutdown.
+     */
     SHUTDOWN = 1
 }
 export interface IWillSaveStateEvent {
@@ -29,21 +35,60 @@ export interface IApplicationStorageValueChangeEvent extends IStorageValueChange
     readonly scope: StorageScope.APPLICATION;
 }
 export declare enum StorageScope {
+    /**
+     * The stored data will be scoped to all workspaces across all profiles.
+     */
     APPLICATION = -1,
+    /**
+     * The stored data will be scoped to all workspaces of the same profile.
+     */
     PROFILE = 0,
+    /**
+     * The stored data will be scoped to the current workspace.
+     */
     WORKSPACE = 1
 }
 export declare enum StorageTarget {
+    /**
+     * The stored data is user specific and applies across machines.
+     */
     USER = 0,
+    /**
+     * The stored data is machine specific.
+     */
     MACHINE = 1
 }
 export interface IStorageValueChangeEvent {
+    /**
+     * The scope for the storage entry that changed
+     * or was removed.
+     */
     readonly scope: StorageScope;
+    /**
+     * The `key` of the storage entry that was changed
+     * or was removed.
+     */
     readonly key: string;
+    /**
+     * The `target` can be `undefined` if a key is being
+     * removed.
+     */
     readonly target: StorageTarget | undefined;
+    /**
+     * A hint how the storage change event was triggered. If
+     * `true`, the storage change was triggered by an external
+     * source, such as:
+     * - another process (for example another window)
+     * - operations such as settings sync or profiles change
+     */
     readonly external?: boolean;
 }
 export interface IStorageTargetChangeEvent {
+    /**
+     * The scope for the target that changed. Listeners
+     * should use `keys(scope, target)` to get an updated
+     * list of keys for the given `scope` and `target`.
+     */
     readonly scope: StorageScope;
 }
 interface IKeyTargets {

package/vscode/src/vs/platform/storage/common/storage.service.d.ts

@@ -7,28 +7,148 @@ import { StorageScope, IWorkspaceStorageValueChangeEvent, IProfileStorageValueCh
 export declare const IStorageService: import("../../instantiation/common/instantiation.js").ServiceIdentifier<IStorageService>;
 export interface IStorageService {
     readonly _serviceBrand: undefined;
+    /**
+    * Emitted whenever data is updated or deleted on the given
+    * scope and optional key.
+    *
+    * @param scope the `StorageScope` to listen to changes
+    * @param key the optional key to filter for or all keys of
+    * the scope if `undefined`
+    */
     onDidChangeValue(scope: StorageScope.WORKSPACE, key: string | undefined, disposable: DisposableStore): Event<IWorkspaceStorageValueChangeEvent>;
     onDidChangeValue(scope: StorageScope.PROFILE, key: string | undefined, disposable: DisposableStore): Event<IProfileStorageValueChangeEvent>;
     onDidChangeValue(scope: StorageScope.APPLICATION, key: string | undefined, disposable: DisposableStore): Event<IApplicationStorageValueChangeEvent>;
     onDidChangeValue(scope: StorageScope, key: string | undefined, disposable: DisposableStore): Event<IStorageValueChangeEvent>;
+    /**
+    * Emitted whenever target of a storage entry changes.
+    */
     readonly onDidChangeTarget: Event<IStorageTargetChangeEvent>;
+    /**
+    * Emitted when the storage is about to persist. This is the right time
+    * to persist data to ensure it is stored before the application shuts
+    * down.
+    *
+    * The will save state event allows to optionally ask for the reason of
+    * saving the state, e.g. to find out if the state is saved due to a
+    * shutdown.
+    *
+    * Note: this event may be fired many times, not only on shutdown to prevent
+    * loss of state in situations where the shutdown is not sufficient to
+    * persist the data properly.
+    */
     readonly onWillSaveState: Event<IWillSaveStateEvent>;
+    /**
+    * Retrieve an element stored with the given key from storage. Use
+    * the provided `defaultValue` if the element is `null` or `undefined`.
+    *
+    * @param scope allows to define the scope of the storage operation
+    * to either the current workspace only, all workspaces or all profiles.
+    */
     get(key: string, scope: StorageScope, fallbackValue: string): string;
     get(key: string, scope: StorageScope, fallbackValue?: string): string | undefined;
+    /**
+    * Retrieve an element stored with the given key from storage. Use
+    * the provided `defaultValue` if the element is `null` or `undefined`.
+    * The element will be converted to a `boolean`.
+    *
+    * @param scope allows to define the scope of the storage operation
+    * to either the current workspace only, all workspaces or all profiles.
+    */
     getBoolean(key: string, scope: StorageScope, fallbackValue: boolean): boolean;
     getBoolean(key: string, scope: StorageScope, fallbackValue?: boolean): boolean | undefined;
+    /**
+    * Retrieve an element stored with the given key from storage. Use
+    * the provided `defaultValue` if the element is `null` or `undefined`.
+    * The element will be converted to a `number` using `parseInt` with a
+    * base of `10`.
+    *
+    * @param scope allows to define the scope of the storage operation
+    * to either the current workspace only, all workspaces or all profiles.
+    */
     getNumber(key: string, scope: StorageScope, fallbackValue: number): number;
     getNumber(key: string, scope: StorageScope, fallbackValue?: number): number | undefined;
+    /**
+    * Retrieve an element stored with the given key from storage. Use
+    * the provided `defaultValue` if the element is `null` or `undefined`.
+    * The element will be converted to a `object` using `JSON.parse`.
+    *
+    * @param scope allows to define the scope of the storage operation
+    * to either the current workspace only, all workspaces or all profiles.
+    */
     getObject<T extends object>(key: string, scope: StorageScope, fallbackValue: T): T;
     getObject<T extends object>(key: string, scope: StorageScope, fallbackValue?: T): T | undefined;
+    /**
+    * Store a value under the given key to storage. The value will be
+    * converted to a `string`. Storing either `undefined` or `null` will
+    * remove the entry under the key.
+    *
+    * @param scope allows to define the scope of the storage operation
+    * to either the current workspace only, all workspaces or all profiles.
+    *
+    * @param target allows to define the target of the storage operation
+    * to either the current machine or user.
+    */
     store(key: string, value: StorageValue, scope: StorageScope, target: StorageTarget): void;
+    /**
+    * Allows to store multiple values in a bulk operation. Events will only
+    * be emitted when all values have been stored.
+    *
+    * @param external a hint to indicate the source of the operation is external,
+    * such as settings sync or profile changes.
+    */
     storeAll(entries: Array<IStorageEntry>, external: boolean): void;
+    /**
+    * Delete an element stored under the provided key from storage.
+    *
+    * The scope argument allows to define the scope of the storage
+    * operation to either the current workspace only, all workspaces
+    * or all profiles.
+    */
     remove(key: string, scope: StorageScope): void;
+    /**
+    * Returns all the keys used in the storage for the provided `scope`
+    * and `target`.
+    *
+    * Note: this will NOT return all keys stored in the storage layer.
+    * Some keys may not have an associated `StorageTarget` and thus
+    * will be excluded from the results.
+    *
+    * @param scope allows to define the scope for the keys
+    * to either the current workspace only, all workspaces or all profiles.
+    *
+    * @param target allows to define the target for the keys
+    * to either the current machine or user.
+    */
     keys(scope: StorageScope, target: StorageTarget): string[];
+    /**
+    * Log the contents of the storage to the console.
+    */
     log(): void;
+    /**
+    * Returns true if the storage service handles the provided scope.
+    */
     hasScope(scope: IAnyWorkspaceIdentifier | IUserDataProfile): boolean;
+    /**
+    * Switch storage to another workspace or profile. Optionally preserve the
+    * current data to the new storage.
+    */
     switch(to: IAnyWorkspaceIdentifier | IUserDataProfile, preserveData: boolean): Promise<void>;
+    /**
+    * Whether the storage for the given scope was created during this session or
+    * existed before.
+    */
     isNew(scope: StorageScope): boolean;
+    /**
+    * Attempts to reduce the DB size via optimization commands if supported.
+    */
     optimize(scope: StorageScope): Promise<void>;
+    /**
+    * Allows to flush state, e.g. in cases where a shutdown is
+    * imminent. This will send out the `onWillSaveState` to ask
+    * everyone for latest state.
+    *
+    * @returns a `Promise` that can be awaited on when all updates
+    * to the underlying storage have been flushed.
+    */
     flush(reason?: WillSaveStateReason): Promise<void>;
 }

package/vscode/src/vs/platform/telemetry/common/telemetry.service.d.ts

@@ -10,9 +10,22 @@ export interface ITelemetryService {
     readonly devDeviceId: string;
     readonly firstSessionDate: string;
     readonly msftInternal?: boolean;
+    /**
+    * Whether error telemetry will get sent. If false, `publicLogError` will no-op.
+    */
     readonly sendErrorTelemetry: boolean;
+    /**
+    * @deprecated Use publicLog2 and the typescript GDPR annotation where possible
+    */
     publicLog(eventName: string, data?: ITelemetryData): void;
+    /**
+    * Sends a telemetry event that has been privacy approved.
+    * Do not call this unless you have been given approval.
+    */
     publicLog2<E extends ClassifiedEvent<OmitMetadata<T>> = never, T extends IGDPRProperty = never>(eventName: string, data?: StrictPropertyCheck<T, E>): void;
+    /**
+    * @deprecated Use publicLogError2 and the typescript GDPR annotation where possible
+    */
     publicLogError(errorEventName: string, data?: ITelemetryData): void;
     publicLogError2<E extends ClassifiedEvent<OmitMetadata<T>> = never, T extends IGDPRProperty = never>(eventName: string, data?: StrictPropertyCheck<T, E>): void;
     setExperimentProperty(name: string, value: string): void;

package/vscode/src/vs/platform/telemetry/common/telemetryUtils.d.ts

@@ -6,6 +6,11 @@ import { IProductService } from "../../product/common/productService.service.js"
 import { ITelemetryData, ITelemetryEndpoint, TelemetryLevel } from "./telemetry.js";
 import { ICustomEndpointTelemetryService } from "./telemetry.service.js";
 import { ITelemetryService } from "./telemetry.service.js";
+/**
+ * A special class used to denoting a telemetry value which should not be clean.
+ * This is because that value is "Trusted" not to contain identifiable information such as paths.
+ * NOTE: This is used as an API type as well, and should not be changed.
+ */
 export declare class TelemetryTrustedValue<T> {
     readonly value: T;
     readonly isTrustedTelemetryValue = true;
@@ -45,8 +50,31 @@ export interface URIDescriptor {
     ext?: string;
     path?: string;
 }
+/**
+ * Determines whether or not we support logging telemetry.
+ * This checks if the product is capable of collecting telemetry but not whether or not it can send it
+ * For checking the user setting and what telemetry you can send please check `getTelemetryLevel`.
+ * This returns true if `--disable-telemetry` wasn't used, the product.json allows for telemetry, and we're not testing an extension
+ * If false telemetry is disabled throughout the product
+ * @param productService
+ * @param environmentService
+ * @returns false - telemetry is completely disabled, true - telemetry is logged locally, but may not be sent
+ */
 export declare function supportsTelemetry(productService: IProductService, environmentService: IEnvironmentService): boolean;
+/**
+ * Checks to see if we're in logging only mode to debug telemetry.
+ * This is if telemetry is enabled and we're in OSS, but no telemetry key is provided so it's not being sent just logged.
+ * @param productService
+ * @param environmentService
+ * @returns True if telemetry is actually disabled and we're only logging for debug purposes
+ */
 export declare function isLoggingOnly(productService: IProductService, environmentService: IEnvironmentService): boolean;
+/**
+ * Determines how telemetry is handled based on the user's configuration.
+ *
+ * @param configurationService
+ * @returns OFF, ERROR, ON
+ */
 export declare function getTelemetryLevel(configurationService: IConfigurationService): TelemetryLevel;
 export interface Properties {
     [key: string]: string;
@@ -59,6 +87,12 @@ export declare function validateTelemetryData(data?: any): {
     measurements: Measurements;
 };
 export declare function cleanRemoteAuthority(remoteAuthority?: string): string;
+/**
+ * Whether or not this is an internal user
+ * @param productService The product service
+ * @param configService The config servivce
+ * @returns true if internal, false otherwise
+ */
 export declare function isInternalTelemetry(productService: IProductService, configService: IConfigurationService): boolean;
 interface IPathEnvironment {
     appRoot: string;
@@ -68,5 +102,11 @@ interface IPathEnvironment {
     tmpDir: URI;
 }
 export declare function getPiiPathsFromEnvironment(paths: IPathEnvironment): string[];
+/**
+ * Does a best possible effort to clean a data object from any possible PII.
+ * @param data The data object to clean
+ * @param paths Any additional patterns that should be removed from the data set
+ * @returns A new object with the PII removed
+ */
 export declare function cleanData(data: Record<string, any>, cleanUpPatterns: RegExp[]): Record<string, any>;
 export {};