std.process: Improve doc comments of Windows argv -> command line functions

Author: squeek502

lib/std/process.zig

@@ -1934,6 +1934,8 @@ pub const WindowsCommandLineCache = struct {
     }
 };
 
+/// Returns the absolute path of `cmd.exe` within the Windows system directory.
+/// The caller owns the returned slice.
 pub fn windowsCmdExePath(allocator: mem.Allocator) error{ OutOfMemory, Unexpected }![:0]u16 {
     var buf = try std.ArrayListUnmanaged(u16).initCapacity(allocator, 128);
     errdefer buf.deinit(allocator);
@@ -1965,6 +1967,11 @@ pub const ArgvToCommandLineError = error{ OutOfMemory, InvalidWtf8, InvalidArg0
 
 /// Serializes `argv` to a Windows command-line string suitable for passing to a child process and
 /// parsing by the `CommandLineToArgvW` algorithm. The caller owns the returned slice.
+///
+/// To avoid arbitrary command execution, this function should not be used when spawning `.bat`/`.cmd` scripts.
+/// https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
+///
+/// When executing `.bat`/`.cmd` scripts, use `argvToScriptCommandLineWindows` instead.
 pub fn argvToCommandLineWindows(
     allocator: mem.Allocator,
     argv: []const []const u8,
@@ -2133,6 +2140,14 @@ pub const ArgvToScriptCommandLineError = error{
 ///
 /// Escapes `argv` using the suggested mitigation against arbitrary command execution from:
 /// https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
+///
+/// The return of this function will look like
+/// `cmd.exe /d /e:ON /v:OFF /c "<escaped command line>"`
+/// and should be used as the `lpCommandLine` of `CreateProcessW`, while the
+/// return of `windowsCmdExePath` should be used as `lpApplicationName`.
+///
+/// Should only be used when spawning `.bat`/`.cmd` scripts, see `argvToCommandLineWindows` otherwise.
+/// The `.bat`/`.cmd` file must be known to both have the `.bat`/`.cmd` extension and exist on the filesystem.
 pub fn argvToScriptCommandLineWindows(
     allocator: mem.Allocator,
     /// Path to the `.bat`/`.cmd` script. If this path is relative, it is assumed to be relative to the CWD.