Add documentation about token parameter

Signed-off-by: Thomas Mäder <tmader@redhat.com>

packages/task/src/browser/task-service.ts

@@ -332,11 +332,23 @@ export class TaskService implements TaskConfigurationClient {
         return `${taskName} (${this.labelProvider.getName(new URI(sourceStrUri))})`;
     }
 
+    /**
+     * Client should call this method to indicate that a new user-level action related to tasks has been started,
+     * like invoking "Run Task..."
+     * This method returns a token that can be used with various methods in this service.
+     * As long as a client uses the same token, task providers will only asked once to contribute
+     * tasks and the set of tasks will be cached. Each time the a new token is used, the cache of
+     * contributed tasks is cleared.
+     * @returns a token to be used for task-related actions
+     */
     startUserAction(): number {
         return this.providedTaskConfigurations.startUserAction();
     }
 
-    /** Returns an array of the task configurations configured in tasks.json and provided by the extensions. */
+    /**
+     * Returns an array of the task configurations configured in tasks.json and provided by the extensions.
+     * @param token  The cache token for the user interaction in progress
+    */
     async getTasks(token: number): Promise<TaskConfiguration[]> {
         const configuredTasks = await this.getConfiguredTasks(token);
         const providedTasks = await this.getProvidedTasks(token);
@@ -346,7 +358,11 @@ export class TaskService implements TaskConfigurationClient {
         return [...configuredTasks, ...notCustomizedProvidedTasks];
     }
 
-    /** Returns an array of the valid task configurations which are configured in tasks.json files */
+    /** 
+     * Returns an array of the valid task configurations which are configured in tasks.json files
+     * @param token  The cache token for the user interaction in progress
+     * 
+     */
     async getConfiguredTasks(token: number): Promise<TaskConfiguration[]> {
         const invalidTaskConfig = this.taskConfigurations.getInvalidTaskConfigurations()[0];
         if (invalidTaskConfig) {
@@ -381,7 +397,10 @@ export class TaskService implements TaskConfigurationClient {
         return validTaskConfigs;
     }
 
-    /** Returns an array of the task configurations which are provided by the extensions. */
+    /** 
+     * Returns an array of the task configurations which are provided by the extensions.
+     * @param token  The cache token for the user interaction in progress
+     */
     getProvidedTasks(token: number): Promise<TaskConfiguration[]> {
         return this.providedTaskConfigurations.getTasks(token);
     }
@@ -421,8 +440,12 @@ export class TaskService implements TaskConfigurationClient {
     }
 
     /**
-     * Returns a task configuration provided by an extension by task source and label.
+     * Returns a task configuration provided by an extension by task source, scope and label.
      * If there are no task configuration, returns undefined.
+     * @param token  The cache token for the user interaction in progress
+     * @param source The source for configured tasks
+     * @param label  The label of the task to find
+     * @param scope  The task scope to look in
      */
     async getProvidedTask(token: number, source: string, label: string, scope: TaskConfigurationScope): Promise<TaskConfiguration | undefined> {
         return this.providedTaskConfigurations.getTask(token, source, label, scope);
@@ -450,6 +473,9 @@ export class TaskService implements TaskConfigurationClient {
     /**
      * Runs a task, by task configuration label.
      * Note, it looks for a task configured in tasks.json only.
+     * @param token  The cache token for the user interaction in progress
+     * @param scope The scope where to look for tasks
+     * @param taskLabel the label to look for
      */
     async runConfiguredTask(token: number, scope: TaskConfigurationScope, taskLabel: string): Promise<void> {
         const task = this.taskConfigurations.getTask(scope, taskLabel);
@@ -463,6 +489,7 @@ export class TaskService implements TaskConfigurationClient {
 
     /**
      * Run the last executed task.
+     * @param token  The cache token for the user interaction in progress
      */
     async runLastTask(token: number): Promise<TaskInfo | undefined> {
         if (!this.lastTask) {
@@ -475,6 +502,10 @@ export class TaskService implements TaskConfigurationClient {
     /**
      * Runs a task, by the source and label of the task configuration.
      * It looks for configured and detected tasks.
+     * @param token  The cache token for the user interaction in progress
+     * @param source The source for configured tasks
+     * @param taskLabel The label to look for 
+     * @param scope  The scope where to look for tasks
      */
     async run(token: number, source: string, taskLabel: string, scope: TaskConfigurationScope): Promise<TaskInfo | undefined> {
         let task: TaskConfiguration | undefined;
@@ -533,6 +564,12 @@ export class TaskService implements TaskConfigurationClient {
         }
     }
 
+    /**
+     * Runs a compound task
+     * @param token  The cache token for the user interaction in progress
+     * @param task The task to be executed
+     * @param option options for executing the task
+     */
     async runCompoundTask(token: number, task: TaskConfiguration, option?: RunTaskOption): Promise<TaskInfo | undefined> {
         const tasks = await this.getWorkspaceTasks(token, task._scope);
         try {
@@ -789,6 +826,12 @@ export class TaskService implements TaskConfigurationClient {
         }
     }
 
+    /**
+     * Runs the first task with the given label.
+     * 
+     * @param token  The cache token for the user interaction in progress
+     * @param taskLabel The label of the task to be executed
+     */
     async runTaskByLabel(token: number, taskLabel: string): Promise<TaskInfo | undefined> {
         const tasks: TaskConfiguration[] = await this.getTasks(token);
         for (const task of tasks) {
@@ -799,6 +842,13 @@ export class TaskService implements TaskConfigurationClient {
         return;
     }
 
+    /**
+     * Runs a task identified by the given identifier, but only if found in the give workspace folder
+     * 
+     * @param token  The cache token for the user interaction in progress
+     * @param workspaceFolderUri  The folder to restrict the search to
+     * @param taskIdentifier The identifier to look for
+     */
     async runWorkspaceTask(token: number, workspaceFolderUri: string | undefined, taskIdentifier: string | TaskIdentifier): Promise<TaskInfo | undefined> {
         const tasks = await this.getWorkspaceTasks(token, workspaceFolderUri);
         const task = this.getDependentTask(taskIdentifier, tasks);
@@ -828,6 +878,7 @@ export class TaskService implements TaskConfigurationClient {
      * Updates the task configuration in the `tasks.json`.
      * The task config, together with updates, will be written into the `tasks.json` if it is not found in the file.
      *
+     * @param token  The cache token for the user interaction in progress
      * @param task task that the updates will be applied to
      * @param update the updates to be applied
      */
@@ -1053,6 +1104,12 @@ export class TaskService implements TaskConfigurationClient {
         }
     }
 
+    /**
+     * Opens an editor to configure the given task.
+     * 
+     * @param token  The cache token for the user interaction in progress
+     * @param task The task to configure
+     */
     async configure(token: number, task: TaskConfiguration): Promise<void> {
         await this.taskConfigurations.configure(token, task);
     }