Please document json file format

[JanKok]

I have had several difficulties due to lack of documentation about the launch.json and tasks.json files. In the latest case, I had trouble passing a file path to my target program. See microsoft/vscode#4057
I think what is needed is:

1. Some documentation for each json file. This documentation should be referenced wherever launch.json and tasks.json are mentioned in the user docs. Also, where these json docs mention the "args": parameter, they should reference item Processing code open source? #2 below. This json documentation doesn't necessarily have to be new web pages. I think it might be adequate to document the format in the files themselves, similar to what is done with Default Settings and settings.json.
2. A detailed explanation of how the "args": parameter is parsed and the args passed to the target. I would suggest several parts to this:
   2.1 Several examples to help get the user on his way. Show the user how to pass:

• File paths that include backslashes, slashes, blanks, wildcards (*, ?,...), environment variables (%WINDOWS%, $PATH, ${file}) and other special characters.
• Zero-length strings, for example sometimes you want to start a program that can talk to X windows but tell it not to talk to X windows, using the call xprogram -d ''
• Literal strings, for example, how to pass ${file} to the target program as the string dollar-sign, open-brace, f, i, ...? This may actually be useful, for example when passing args to the gdb start command, because the start command interprets its args like a shell, so you might want to pass something like $PATH or $MY_ENV_VAR literally to some program.
• Other special characters, such as newline chars (maybe not so useful) or non-ASCII character strings.

2.2 An explanation of the process whereby args get from the json file to the target program, so that the user can understand and figure out how to handle difficult cases not covered by the examples. My understanding is: VSCode parses the json file using certain rules about backslash, double quote, etc., then passes the array of strings to the appropriate extension, which typically passes the args unchanged (or concatenated with spaces) to the target program, which in some cases (such as gdb) may do additional processing on the args.
2.3 Give a simple program in several languages for checking out how args are passed. For example, in PowerShell, this one-line program seems to print the args, one per line:
Write-Output "args:", $args
However, I'm not a PowerShell expert, so that may not be exactly right. PowerShell has a habit of evaluating arguments in unexpected ways. That's why it would be good to have some examples from reliable, expert sources.
3. Extension writers should be advised to reference these documents and also to provide any additional details that may be needed in their own documentation. For example, gdb extensions should mention the additional evaluation step that gdb does with the start args.

[JanKok]

@weinand replied at microsoft/vscode#4057

VS Code only prescribes the fact that launch.json is a json file. The structure and semantics of individual launch configs is contributed by individual debugger extensions via a schema and individual interpretations in the debug adapter.
So the PowerShell debug adapter could accept forward slashes on Windows (like the node debug adapter).
Not being able to pass a space (blank) character embedded within a single argument is definitely a problem of the PowerShell adapter and not a problem of a lack of documentation of the json format.

I (Jan) still think there is a need for the VSCode to document launch.json and other json files within the VSCode docs, regarding whatever is common across all language extensions. For example, are the ${file} and ${workspaceRoot} variables available in all extensions' launch.json?

Also, the fact that both the PowerShell and code-debug (C/C++, gdb) extensions implemented argument passing in non-obvious ways indicates a need for some guidance from the VSCode team. I'll file issues at vscode-powershell and code-debug, but I bet most of the extension projects need to know about this issue, namely

• need for detailed documentation of launch.json and similar files, in particular regarding how args are passed (part of the issue is who should write this documentation - VSCode or the extensions?), and
• (possibly) a need to modify how args are passed to adapt to the needs of the individual languages. (But I'd prefer to see this done in a consistent way across all languages, rather than being done ad hoc by each extension developer - hence my call for guidance from VSCode team.)

[JanKok]

If people agree with my outline above, I'm willing to write a couple of pages of documentation, one for a general (not language-specific) launch.json, and another for argument passing. Someone else would have to correct errors and fill in details that I don't know about.
Would that be useful? Should I put the drafts here on vscode-docs?

[weinand]

@JanKok I'm fine with that. Here is what we currently have: https://code.visualstudio.com/docs/editor/debugging#_launch-configurations.
Variable substitution is explained here: http://code.visualstudio.com/docs/editor/tasks#_variable-substitution.
Please note: The information provided by Intellisense and hover help should be sufficient to create and edit a launch.json. Doc is nice to have but less often used than we would hope for.

What is needed is a guide for debug adapter authors, e.g. as a section of http://code.visualstudio.com/docs/extensionAPI/api-debugging.

[raregrass]

That's very helpful. I think documents for lanch.json and tasks.json will give new coming people like me a big picture about what could be use in vscode and how it does.

For vscode, IMO, those config files maybe the barriers to entry. Thanks for your job if you could put some docs.

[JimiC]

👍 for adding launch.json schema documentation.

[gregvanl]

launch.json documentation was updated during the December doc-a-thon.