Fix documentation in dart:io.

sdk/lib/io/process.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 // TODO(ager): The only reason for this class is that we
 // cannot patch a top-level at this point.
 class _ProcessUtils {
   external static void _exit(int status);
@@ skipping 83 matching lines @@
   _ProcessUtils._sleep(milliseconds);
 }
 
 /**
  * Returns the PID of the current process.
  */
 int get pid => _ProcessUtils._pid(null);
 
 /**
  * The means to execute a program.
- * 
+ *
  * Use the static [start] and [run] methods to start a new process.
  * The run method executes the process non-interactively to completion.
  * In contrast, the start method allows your code to interact with the
  * running process.
  *
  * ## Start a process with the run method
  *
  * The following code sample uses the run method to create a process
  * that runs the UNIX command `ls`, which lists the contents of a directory.
  * The run method completes with a [ProcessResult] object when the process
@@ skipping 31 matching lines @@
  *         process.stdout
  *             .transform(UTF8.decoder)
  *             .listen((data) { print(data); });
  *         process.stdin.writeln('Hello, world!');
  *         process.stdin.writeln('Hello, galaxy!');
  *         process.stdin.writeln('Hello, universe!');
  *       });
  *     }
  *
  * ## Standard I/O streams
- * 
+ *
  * As seen in the previous code sample, you can interact with the Process's
  * standard output stream through the getter [stdout],
- * and you can interact with the Process's standard input stream through 
+ * and you can interact with the Process's standard input stream through
  * the getter [stdin].
  * In addition, Process provides a getter [stderr] for using the Process's
  * standard error stream.
  *
  * A Process's streams are distinct from the top-level streams
  * for the current program.
  *
  * ## Exit codes
  *
  * Call the [exitCode] method to get the exit code of the process.
@@ skipping 12 matching lines @@
  *         // Get the exit code from the new process.
  *         process.exitCode.then((exitCode) {
  *           print('exit code: $exitCode');
  *         });
  *       });
  *     }
  *
  * ## Other resources
  *
  * [Dart by Example](https://www.dartlang.org/dart-by-example/#dart-io-and-command-line-apps)
- * provides additional task-oriented code samples that show how to use 
+ * provides additional task-oriented code samples that show how to use
  * various API from the [dart:io] library.
  */
 abstract class Process {
   /**
    * Returns a [:Future:] which completes with the exit code of the process
    * when the process completes.
    *
    * The handling of exit codes is platform specific.
    *
    * On Linux and Mac a normal exit code will be a positive value in
@@ skipping 201 matching lines @@
   /**
    * Process id from the process.
    */
   int get pid;
 }
 
 
 /**
  * On Posix systems, [ProcessSignal] is used to send a specific signal
  * to a child process, see [:Process.kill:].
+ *
+ * Some [ProcessSignal]s can also be watched, as a way to intercept the default
+ * signal handler and implement another. See [ProcessSignal.watch] for more
+ * information.
  */
 class ProcessSignal {
   static const ProcessSignal SIGHUP = const ProcessSignal._(1, "SIGHUP");
   static const ProcessSignal SIGINT = const ProcessSignal._(2, "SIGINT");
   static const ProcessSignal SIGQUIT = const ProcessSignal._(3, "SIGQUIT");
   static const ProcessSignal SIGILL = const ProcessSignal._(4, "SIGILL");
   static const ProcessSignal SIGTRAP = const ProcessSignal._(5, "SIGTRAP");
   static const ProcessSignal SIGABRT = const ProcessSignal._(6, "SIGABRT");
   static const ProcessSignal SIGBUS = const ProcessSignal._(7, "SIGBUS");
   static const ProcessSignal SIGFPE = const ProcessSignal._(8, "SIGFPE");
@@ skipping 25 matching lines @@
   const ProcessSignal._(this._signalNumber, this._name);
 
   String toString() => _name;
 
   /**
    * Watch for process signals.
    *
    * The following [ProcessSignal]s can be listened to:
    *
    *   * [ProcessSignal.SIGHUP].
-   *   * [ProcessSignal.SIGINT].
+   *   * [ProcessSignal.SIGINT]. Signal sent by e.g. CTRL-C.
    *   * [ProcessSignal.SIGTERM]. Not available on Windows.
    *   * [ProcessSignal.SIGUSR1]. Not available on Windows.
    *   * [ProcessSignal.SIGUSR2]. Not available on Windows.
    *   * [ProcessSignal.SIGWINCH]. Not available on Windows.
    *
    * Other signals are disallowed, as they may be used by the VM.
+   *
+   * A signal can be watched multiple times, from multiple isolates, where all
+   * callbacks are invoked when signaled, in no specific order.
    */
   Stream<ProcessSignal> watch() => _ProcessUtils._watchSignal(this);
 }
 
 
 class SignalException implements IOException {
   final String message;
   final osError;
 
   const SignalException(this.message, [this.osError = null]);
@@ skipping 30 matching lines @@
   final int errorCode;
 
   const ProcessException(this.executable, this.arguments, [this.message = "",
                          this.errorCode = 0]);
   String toString() {
     var msg = (message == null) ? 'OS error code: $errorCode' : message;
     var args = arguments.join(' ');
     return "ProcessException: $msg\n  Command: $executable $args";
   }
 }