@codingame/monaco-vscode-api 20.1.1 → 20.2.0

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

@@ -10,11 +10,21 @@ import { TerminalExitReason } from "../../../../platform/terminal/common/termina
 export * from "./constants.js";
 export declare const USER_TASKS_GROUP_KEY = "settings";
 export declare const TASK_RUNNING_STATE: RawContextKey<boolean>;
+/** Whether the active terminal is a task terminal. */
 export declare const TASK_TERMINAL_ACTIVE: RawContextKey<boolean>;
 export declare const TASKS_CATEGORY: nls.ILocalizedString;
 export declare enum ShellQuoting {
+    /**
+     * Use character escaping.
+     */
     Escape = 1,
+    /**
+     * Use strong quoting
+     */
     Strong = 2,
+    /**
+     * Use weak quoting.
+     */
     Weak = 3
 }
 export declare const CUSTOMIZED_TASK_TYPE = "$customized";
@@ -22,21 +32,50 @@ export declare namespace ShellQuoting {
     function from(this: void, value: string): ShellQuoting;
 }
 export interface IShellQuotingOptions {
+    /**
+     * The character used to do character escaping.
+     */
     escape?: string | {
         escapeChar: string;
         charsToEscape: string;
     };
+    /**
+     * The character used for string quoting.
+     */
     strong?: string;
+    /**
+     * The character used for weak quoting.
+     */
     weak?: string;
 }
 export interface IShellConfiguration {
+    /**
+     * The shell executable.
+     */
     executable?: string;
+    /**
+     * The arguments to be passed to the shell executable.
+     */
     args?: string[];
+    /**
+     * Which kind of quotes the shell supports.
+     */
     quoting?: IShellQuotingOptions;
 }
 export interface CommandOptions {
+    /**
+     * The shell to use if the task is a shell command.
+     */
     shell?: IShellConfiguration;
+    /**
+     * The current working directory of the executed program or shell.
+     * If omitted VSCode's current workspace root is used.
+     */
     cwd?: string;
+    /**
+     * The environment of the executed program or shell. If omitted
+     * the parent process' environment is used.
+     */
     env?: {
         [key: string]: string;
     };
@@ -45,38 +84,101 @@ export declare namespace CommandOptions {
     const defaults: CommandOptions;
 }
 export declare enum RevealKind {
+    /**
+     * Always brings the terminal to front if the task is executed.
+     */
     Always = 1,
+    /**
+     * Only brings the terminal to front if a problem is detected executing the task
+     * e.g. the task couldn't be started,
+     * the task ended with an exit code other than zero,
+     * or the problem matcher found an error.
+     */
     Silent = 2,
+    /**
+     * The terminal never comes to front when the task is executed.
+     */
     Never = 3
 }
 export declare namespace RevealKind {
     function fromString(this: void, value: string): RevealKind;
 }
 export declare enum RevealProblemKind {
+    /**
+     * Never reveals the problems panel when this task is executed.
+     */
     Never = 1,
+    /**
+     * Only reveals the problems panel if a problem is found.
+     */
     OnProblem = 2,
+    /**
+     * Never reveals the problems panel when this task is executed.
+     */
     Always = 3
 }
 export declare namespace RevealProblemKind {
     function fromString(this: void, value: string): RevealProblemKind;
 }
 export declare enum PanelKind {
+    /**
+     * Shares a panel with other tasks. This is the default.
+     */
     Shared = 1,
+    /**
+     * Uses a dedicated panel for this tasks. The panel is not
+     * shared with other tasks.
+     */
     Dedicated = 2,
+    /**
+     * Creates a new panel whenever this task is executed.
+     */
     New = 3
 }
 export declare namespace PanelKind {
     function fromString(value: string): PanelKind;
 }
 export interface IPresentationOptions {
+    /**
+     * Controls whether the task output is reveal in the user interface.
+     * Defaults to `RevealKind.Always`.
+     */
     reveal: RevealKind;
+    /**
+     * Controls whether the problems pane is revealed when running this task or not.
+     * Defaults to `RevealProblemKind.Never`.
+     */
     revealProblems: RevealProblemKind;
+    /**
+     * Controls whether the command associated with the task is echoed
+     * in the user interface.
+     */
     echo: boolean;
+    /**
+     * Controls whether the panel showing the task output is taking focus.
+     */
     focus: boolean;
+    /**
+     * Controls if the task panel is used for this task only (dedicated),
+     * shared between tasks (shared) or if a new panel is created on
+     * every task execution (new). Defaults to `TaskInstanceKind.Shared`
+     */
     panel: PanelKind;
+    /**
+     * Controls whether to show the "Terminal will be reused by tasks, press any key to close it" message.
+     */
     showReuseMessage: boolean;
+    /**
+     * Controls whether to clear the terminal before executing the task.
+     */
     clear: boolean;
+    /**
+     * Controls whether the task is executed in a specific terminal group using split panes.
+     */
     group?: string;
+    /**
+     * Controls whether the terminal that the task runs in is closed when the task completes.
+     */
     close?: boolean;
 }
 export declare namespace PresentationOptions {
@@ -100,12 +202,34 @@ export declare namespace CommandString {
     function value(value: CommandString): string;
 }
 export interface ICommandConfiguration {
+    /**
+     * The task type
+     */
     runtime?: RuntimeType;
+    /**
+     * The command to execute
+     */
     name?: CommandString;
+    /**
+     * Additional command options.
+     */
     options?: CommandOptions;
+    /**
+     * Command arguments.
+     */
     args?: CommandString[];
+    /**
+     * The task selector if needed.
+     */
     taskSelector?: string;
+    /**
+     * Whether to suppress the task name when merging global args
+     *
+     */
     suppressTaskName?: boolean;
+    /**
+     * Describes how the task is presented in the UI.
+     */
     presentation?: IPresentationOptions;
 }
 export declare namespace TaskGroup {
@@ -193,21 +317,60 @@ export declare enum DependsOrder {
     sequence = "sequence"
 }
 export interface IConfigurationProperties {
+    /**
+     * The task's name
+     */
     name?: string;
+    /**
+     * The task's name
+     */
     identifier?: string;
+    /**
+     * The task's group;
+     */
     group?: string | TaskGroup;
+    /**
+     * The presentation options
+     */
     presentation?: IPresentationOptions;
+    /**
+     * The command options;
+     */
     options?: CommandOptions;
+    /**
+     * Whether the task is a background task or not.
+     */
     isBackground?: boolean;
+    /**
+     * Whether the task should prompt on close for confirmation if running.
+     */
     promptOnClose?: boolean;
+    /**
+     * The other tasks this task depends on.
+     */
     dependsOn?: ITaskDependency[];
+    /**
+     * The order the dependsOn tasks should be executed in.
+     */
     dependsOrder?: DependsOrder;
+    /**
+     * A description of the task.
+     */
     detail?: string;
+    /**
+     * The problem watchers to use for this task
+     */
     problemMatchers?: Array<string | ProblemMatcher>;
+    /**
+     * The icon for this task in the terminal tabs list
+     */
     icon?: {
         id?: string;
         color?: string;
     };
+    /**
+     * Do not show this task in the run task quickpick
+     */
     hide?: boolean;
 }
 export declare enum RunOnOptions {
@@ -231,7 +394,13 @@ export declare namespace RunOptions {
     const defaults: IRunOptions;
 }
 export declare abstract class CommonTask {
+    /**
+     * The task's internal id
+     */
     readonly _id: string;
+    /**
+     * The cached label.
+     */
     _label: string;
     type?: string;
     runOptions: IRunOptions;
@@ -255,11 +424,23 @@ export declare abstract class CommonTask {
     addTaskLoadMessages(messages: string[] | undefined): void;
     get taskLoadMessages(): string[] | undefined;
 }
+/**
+ * For tasks of type shell or process, this is created upon parse
+ * of the tasks.json or workspace file.
+ * For ContributedTasks of all other types, this is the result of
+ * resolving a ConfiguringTask.
+ */
 export declare class CustomTask extends CommonTask {
     type: "$customized";
     instance: number | undefined;
+    /**
+     * Indicated the source of the task (e.g. tasks.json or extension)
+     */
     _source: FileBasedTaskSource;
     hasDefinedMatchers: boolean;
+    /**
+     * The command configuration
+     */
     command: ICommandConfiguration;
     constructor(id: string, source: FileBasedTaskSource, label: string, type: string, command: ICommandConfiguration | undefined, hasDefinedMatchers: boolean, runOptions: IRunOptions, configurationProperties: IConfigurationProperties);
     clone(): CustomTask;
@@ -269,13 +450,24 @@ export declare class CustomTask extends CommonTask {
     getMapKey(): string;
     protected getFolderId(): string | undefined;
     getCommonTaskId(): string;
+    /**
+     * @returns A key representing the task
+     */
     getKey(): string | undefined;
     getWorkspaceFolder(): IWorkspaceFolder | undefined;
     getWorkspaceFileName(): string | undefined;
     getTelemetryKind(): string;
     protected fromObject(object: CustomTask): CustomTask;
 }
+/**
+ * After a contributed task has been parsed, but before
+ * the task has been resolved via the extension, its properties
+ * are stored in this
+ */
 export declare class ConfiguringTask extends CommonTask {
+    /**
+     * Indicated the source of the task (e.g. tasks.json or extension)
+     */
     _source: FileBasedTaskSource;
     configures: KeyedTaskIdentifier;
     constructor(id: string, source: FileBasedTaskSource, label: string | undefined, type: string | undefined, configures: KeyedTaskIdentifier, runOptions: IRunOptions, configurationProperties: IConfigurationProperties);
@@ -287,16 +479,32 @@ export declare class ConfiguringTask extends CommonTask {
     protected getFolderId(): string | undefined;
     getKey(): string | undefined;
 }
+/**
+ * A task from an extension created via resolveTask or provideTask
+ */
 export declare class ContributedTask extends CommonTask {
+    /**
+     * Indicated the source of the task (e.g. tasks.json or extension)
+     * Set in the super constructor
+     */
     _source: IExtensionTaskSource;
     instance: number | undefined;
     defines: KeyedTaskIdentifier;
     hasDefinedMatchers: boolean;
+    /**
+     * The command configuration
+     */
     command: ICommandConfiguration;
+    /**
+     * The icon for the task
+     */
     icon: {
         id?: string;
         color?: string;
     } | undefined;
+    /**
+     * Don't show the task in the run task quickpick
+     */
     hide?: boolean;
     constructor(id: string, source: IExtensionTaskSource, label: string, type: string | undefined, defines: KeyedTaskIdentifier, command: ICommandConfiguration, hasDefinedMatchers: boolean, runOptions: IRunOptions, configurationProperties: IConfigurationProperties);
     clone(): ContributedTask;
@@ -310,6 +518,9 @@ export declare class ContributedTask extends CommonTask {
     protected fromObject(object: ContributedTask): ContributedTask;
 }
 export declare class InMemoryTask extends CommonTask {
+    /**
+     * Indicated the source of the task (e.g. tasks.json or extension)
+     */
     _source: IInMemoryTaskSource;
     instance: number | undefined;
     type: "inMemory";
@@ -361,18 +572,31 @@ export interface ITaskChangedEvent {
     kind: TaskEventKind.Changed;
 }
 export declare enum TaskEventKind {
+    /** Indicates that a task's properties or configuration have changed */
     Changed = "changed",
+    /** Indicates that a task has begun executing */
     ProcessStarted = "processStarted",
+    /** Indicates that a task process has completed */
     ProcessEnded = "processEnded",
+    /** Indicates that a task was terminated, either by user action or by the system */
     Terminated = "terminated",
+    /** Indicates that a task has started running */
     Start = "start",
+    /** Indicates that a task has acquired all needed input/variables to execute */
     AcquiredInput = "acquiredInput",
+    /** Indicates that a dependent task has started */
     DependsOnStarted = "dependsOnStarted",
+    /** Indicates that a task is actively running/processing */
     Active = "active",
+    /** Indicates that a task is paused/waiting but not complete */
     Inactive = "inactive",
+    /** Indicates that a task has completed fully */
     End = "end",
+    /** Indicates that a task's problem matcher has started */
     ProblemMatcherStarted = "problemMatcherStarted",
+    /** Indicates that a task's problem matcher has ended */
     ProblemMatcherEnded = "problemMatcherEnded",
+    /** Indicates that a task's problem matcher has found errors */
     ProblemMatcherFoundErrors = "problemMatcherFoundErrors"
 }
 interface ITaskCommon {