[doc, io]: Add a note to indicate the batch file execution behavior on Windows.

Change-Id: I6f61af46e7e9e96282127fea919c8e79948356d4
CoreLibraryReviewExempt: documentation only
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/364941
Commit-Queue: Brian Quinlan <[email protected]>
Reviewed-by: Alexander Aprelev <[email protected]>

Author: brianquinlan

sdk/lib/io/process.dart

@@ -321,6 +321,18 @@ abstract interface class Process {
   /// shell. On Linux and OS X, `/bin/sh` is used, while
   /// `%WINDIR%\system32\cmd.exe` is used on Windows.
   ///
+  /// **NOTE**: On Windows, if [executable] is a batch file
+  /// ('*.bat' or '*.cmd'), it may be launched by the operating system in a
+  /// system shell regardless of the value of [runInShell]. This could result in
+  /// arguments being parsed according to shell rules. For example:
+  ///
+  /// ```
+  /// void main() async {
+  ///   // Will launch notepad.
+  ///   Process.start('test.bat', ['test&notepad.exe']);
+  /// }
+  /// ```
+  ///
   /// Users must read all data coming on the [stdout] and [stderr]
   /// streams of processes started with `Process.start`. If the user
   /// does not read all data on the streams the underlying system
@@ -388,6 +400,18 @@ abstract interface class Process {
   /// shell. On Linux and OS X, `/bin/sh` is used, while
   /// `%WINDIR%\system32\cmd.exe` is used on Windows.
   ///
+  /// **NOTE**: On Windows, if [executable] is a batch file
+  /// ('*.bat' or '*.cmd'), it may be launched by the operating system in a
+  /// system shell regardless of the value of [runInShell]. This could result in
+  /// arguments being parsed according to shell rules. For example:
+  ///
+  /// ```
+  /// void main() async {
+  ///   // Will launch notepad.
+  ///   await Process.run('test.bat', ['test&notepad.exe']);
+  /// }
+  /// ```
+  ///
   /// The encoding used for decoding `stdout` and `stderr` into text is
   /// controlled through [stdoutEncoding] and [stderrEncoding]. The
   /// default encoding is [systemEncoding]. If `null` is used no