Documentation update

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 77 matching lines @@
    * precedence. Default is `true`.
    *
    * If [runInShell] is true, the process will be spawned through a system
    * shell. On Linux and Mac OS, [:/bin/sh:] is used, while
    * [:%WINDIR%\system32\cmd.exe:] is used on Windows.
    *
    * 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
    * resources will not be freed since there is still pending data.
+   *
+   * The following code uses `Process.start` to grep for `main` in the
+   * file `test.dart` on Linux.
+   *
+   *     Process.start('grep', ['-i', 'main', 'test.dart']).then((p) {
+   *       p.stdout.pipe(stdout);

[Anders Johnsen, 2013/11/20 12:24:04]

Please use `stdout.addStream(p.stdout)` and likewise for stderr.

[Søren Gjesse, 2014/01/02 09:19:30]

Done.

+   *       p.stderr.pipe(stderr);
+   *     });
    */
   external static Future<Process> start(
       String executable,
       List<String> arguments,
       {String workingDirectory,
        Map<String, String> environment,
        bool includeParentEnvironment: true,
        bool runInShell: false});
 
   /**
@@ skipping 21 matching lines @@
    *
    * The encoding used for decoding `stdout` and `stderr` into text is
    * controlled through [stdoutEncoding] and [stderrEncoding]. The
    * default encoding is [SYSTEM_ENCODING]. If `null` is used no
    * decoding will happen and the [ProcessResult] will hold binary
    * data.
    *
    * Returns a `Future<ProcessResult>` that completes with the
    * result of running the process, i.e., exit code, standard out and
    * standard in.
+   *
+   * The following code uses `Process.run` to grep for `main` in the
+   * file `test.dart` on Linux.
+   *
+   *     Process.run('grep', ['-i', 'main', 'test.dart']).then((result) {
+   *       stdout.write(result.stdout);
+   *       stdout.write(result.stderr);

[Anders Johnsen, 2013/11/20 12:24:04]

stderr.write

[Søren Gjesse, 2014/01/02 09:19:30]

Done.

+   *     });
    */
   external static Future<ProcessResult> run(
       String executable,
       List<String> arguments,
       {String workingDirectory,
        Map<String, String> environment,
        bool includeParentEnvironment: true,
        bool runInShell: false,
        Encoding stdoutEncoding: SYSTEM_ENCODING,
        Encoding stderrEncoding: SYSTEM_ENCODING});
@@ skipping 169 matching lines @@
   /**
    * Contains the system message for the process exception if any.
    */
   final String message;
 
   /**
    * Contains the OS error code for the process exception if any.
    */
   final int errorCode;
 }