tasks.json schema docs are missing custom task types (e.g. typescript, npm) and also other config properties

[justingrant]

The task.json schema documentation (https://code.visualstudio.com/docs/editor/tasks-appendix) is incomplete and/or out of date. For example, it's missing documentation for NPM and TypeScript task types that are auto-detected by VSCode. Below are examples of two tasks that were auto-detected by VS Code 1.32.2. Other than problemMatcher, none of these settings are documented.

{
  "type": "typescript",
  "tsconfig": "api/tsconfig.json",
  "option": "watch",
  "problemMatcher": [
    "$tsc-watch"
  ]
},
{
  "type": "npm",
  "script": "start",
  "path": "api/",
  "problemMatcher": []
}

In particular, I'm trying to figure out how the option config property works for the typescript task type, because I want to figure out how to to add --noEmit to the typescript command line used for a watch task. But more generally, all settings for all task types should be documented!

If you look at the task auto-detection code (excerpted below), there are at least 5 different task types that are not documented: typescript, npm, gulp, jake, and grunt.

if (customize.indexOf(grunt) === 0) {
  identifier = { type: 'grunt', task: customize.substring(grunt.length) };
} else if (customize.indexOf(jake) === 0) {
  identifier = { type: 'jake', task: customize.substring(jake.length) };
} else if (customize.indexOf(gulp) === 0) {
  identifier = { type: 'gulp', task: customize.substring(gulp.length) };
} else if (customize.indexOf(npm) === 0) {
  identifier = { type: 'npm', script: customize.substring(npm.length + 4) };
} else if (customize.indexOf(typescript) === 0) {
  identifier = { type: 'typescript', tsconfig: customize.substring(typescript.length + 6) };
}

Besides different type values (and the undocumented settings they use), there are other settings in the documentation that seem to be out of date compared with the source here: https://github.com/Microsoft/vscode/blob/master/src/vs/workbench/contrib/tasks/node/taskConfiguration.ts#L28-L506
For example, the following properties are in the code but not the docs. I'm not sure if all of these correspond to user-facing config settings, but I assume at least some do:

• CommandOptions.shell.quoting
• PresentationOptions.showReuseMessage
• PresentationOptions.clear
• PresentationOptions.group
• ConfigurationProperties.taskName
• ConfigurationProperties.identifier
• ConfigurationProperties.promptOnClose
• ConfigurationProperties.dependsOn
• ConfigurationProperties.options

[alexr00]

This is a tough one. Our schema isn't entirely static, we build it at runtime. Some things are easy to document (like dependsOn) but others, like tasks types, are added to the schema based on what extensions, included built in extensions are installed. So in addition to the types you list, you could have many more from installed extensions.

There is some documentation in the builtin extensions readmes about the tasks, but we can add more with good examples. It would also be good to have links to those readmes in the auto detection documentation.

Almost of these that aren't deprecated are in the docs (not the schema appendix). The only one I see missing is promptOnClose

CommandOptions.shell.quoting
PresentationOptions.showReuseMessage
PresentationOptions.clear
PresentationOptions.group
ConfigurationProperties.taskName
ConfigurationProperties.identifier
ConfigurationProperties.promptOnClose
ConfigurationProperties.dependsOn
ConfigurationProperties.options

Now that I'm thinking about it, it seems like we should just remove the whole schema and instead encourage exploration by opening a tasks.json file in VS Code and using the "Trigger Suggest" command to see what you can do.

[gregvanl]

Moving to October to reconsider if we want to keep the schema topic.