[docs] Clarify & update JSONCompilationDatabase docs

[sammccall]

Summary

• prefer arguments over command, and add example
• clarify that there's no shell-unescaping of arguments

Fixes https://github.com/llvm/llvm-project/issues/53143

[sammccall]

clang/docs/JSONCompilationDatabase.rst

95

Hopefully I'm not too far out on a limb here.

Today, command is generated by CMake & others. The shell unescaping performed is underspecified and platform-specific (#if _WIN32 ... #else). There are non-llvm consumers of this format (e.g. vscode-cpptools).

I think we're in danger of interop problems and gently encouraging migration to arguments reduces the danger.

[hokein]

clang/docs/JSONCompilationDatabase.rst

95

yeah, the arguments was added 7 years ago, and most of tools are still generating command...

clang/docs/JSONCompilationDatabase.rst

 working directory of the compile run and the actual compile command.
 
 Example:
 
 ::
 
     [
       { "directory": "/home/user/llvm/build",
-        "command": "/usr/bin/clang++ -Irelative -DSOMEDEF=\"With spaces, quotes and \\-es.\" -c -o file.o file.cc",
+        "arguments": ["/usr/bin/clang++", "-Irelative", "-DSOMEDEF=With spaces, quotes and \\-es.", "-c", "-o", "file.o", "file.cc"],
         "file": "file.cc" },
+
+      { "directory": "/home/user/llvm/build",
+        "command": "/usr/bin/clang++ -Irelative -DSOMEDEF=\"With spaces, quotes and \\-es.\" -c -o file.o file.cc",
+        "file": "file2.cc" },
+
       ...
     ]
 
 The contracts for each field in the command object are:
 
 -  **directory:** The working directory of the compilation. All paths
    specified in the **command** or **file** fields must be either
    absolute or relative to this directory.
 -  **file:** The main translation unit source processed by this
    compilation step. This is used by tools as the key into the
    compilation database. There can be multiple command objects for the
    same file, for example if the same source file is compiled with
    different configurations.
--  **command:** The compile command executed. After JSON unescaping,
-   this must be a valid command to rerun the exact compilation step for
-   the translation unit in the environment the build system uses.
-   Parameters use shell quoting and shell escaping of quotes, with '``"``'
-   and '``\``' being the only special characters. Shell expansion is not
-   supported.
--  **arguments:** The compile command executed as list of strings.
-   Either **arguments** or **command** is required.
+-  **arguments:** The compile command argv as list of strings.
+   This should run the compilation step for the translation unit ``file``.
+   ``arguments[0]`` should be the executable name, such as ``clang++``.
+   Arguments should not be escaped, but ready to pass to ``execvp()``.
+-  **command:** The compile command as a single shell-escaped string.
+   Arguments may be shell quoted and escaped following platform conventions,
+   with '``"``' and '``\``' being the only special characters. Shell expansion
+   is not supported.
+
+   Either **arguments** or **command** is required. **arguments** is preferred,
+   as shell (un)escaping is a possible source of errors.
 -  **output:** The name of the output created by this compilation step.
    This field is optional. It can be used to distinguish different processing
    modes of the same input file.
 
 Build System Integration
 ========================
 
 The convention is to name the file compile\_commands.json and put it at