class-level docs for several dart:io classes

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 67 matching lines @@
   }
   _ProcessUtils._sleep(milliseconds);
 }
 
 /**
  * Returns the PID of the current process.
  */
 int get pid => _ProcessUtils._pid(null);
 
 /**
- * [Process] is used to start new processes using the static
- * [start] and [run] methods.
+ * 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 process.

[Søren Gjesse, 2014/02/12 13:16:35]

the process -> the running process

[mem, 2014/02/12 19:17:07]

Done.

+ *
+ * ## 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 code gets the output from the standard output stream by way of a

[Søren Gjesse, 2014/02/12 13:16:35]

Instead of the sentence "The code gest ..." something like this:

Run completes with a [ProcessResult] object when the process terminates. This
provides access to the output and exit code from the process.

[mem, 2014/02/12 19:17:07]

Done.

+ * [ProcessResult] object.
+ * The run method does not return a Process object; this prevents your
+ * code from interacting with the running process.
+ *
+ *     import 'dart:io';
+ *
+ *     main() {
+ *       // List all files in the current directory in UNIX-like systems.
+ *       Process.run('ls', ['-l']).then((ProcessResult results) {
+ *         print(results.stdout);
+ *       });
+ *     }
+ *
+ * ## Start a process with the start method
+ *
+ * The following example uses start to create the process.
+ * The start method returns a [Future], which returns a Process object.

[Søren Gjesse, 2014/02/12 13:16:35]

which returns -> for

[mem, 2014/02/12 19:17:07]

Done.

+ * Within the [Future]'s callback function, your code can interact with the

[Søren Gjesse, 2014/02/12 13:16:35]

Within the [Future]'s callback function -> When the future completes the process
is started and

[mem, 2014/02/12 19:17:07]

Done.

+ * Process: writing to stdin, listening to stdout, and so on.
+ *
+ * The following sample starts the UNIX `cat` utility, which when given no
+ * command-line arguments, echos its input.
+ * The program writes to the process's standard input stream
+ * and prints data from its standard output stream.
+ *
+ *     import 'dart:io';
+ *     import 'dart:convert';
+ *
+ *     main() {
+ *       Process.start('cat', []).then((Process proc) {

[Søren Gjesse, 2014/02/12 13:16:35]

Why not spell it out: proc -> process

[mem, 2014/02/12 19:17:07]

Done.

+ *         proc.stdout
+ *             .transform(UTF8.decoder)
+ *             .listen((data) { print(data); });
+ *         proc.stdin.writeln('Hello, world!');
+ *         proc.stdin.writeln('Hello, galaxy!');
+ *         proc.stdin.writeln('Hello, universe!');
+ *       });
+ *     }
+ *
+ * ## Exit codes
+ *
+ * Call the [exitCode] method to get the exit code of the process.
+ * The exit code indicates whether the program terminated successfully
+ * (usually indicated with an exit code of 0) or with an error.
+ * `exitCode` returns the code via a [Future] object.

[Søren Gjesse, 2014/02/12 13:16:35]

`exitCode` returns the code via a [Future] object. ->

If process.start is used the exitCode is available through a future on the
[Process] object. If Process.run is used the exitCode is available through a
getter on the ProcessResult instance.

[mem, 2014/02/12 19:17:07]

Done.

+ *
+ *     import 'dart:io';
+ *
+ *     main() {
+ *       Process.start('ls', ['-l']).then((process) {
+ *         // Get the exit code from the new process.
+ *         process.exitCode.then((exitCode) {
+ *           print('exit code: $exitCode');
+ *         });
+ *       });
+ *     }
+ *
+ * ## Standard streams

[Søren Gjesse, 2014/02/12 13:16:35]

Standard streams -> Standard IO streams

[mem, 2014/02/12 19:17:07]

Done.

+ * 
+ * As seen in a previous code sample, you can use the getters [stderr],

[Søren Gjesse, 2014/02/12 13:16:35]

the getters -> the top-level getters

[mem, 2014/02/12 19:17:07]

Done.

+ * [stdin], and [stdout] to get the process's standard error, standard input,
+ * and standard output streams, respectively.

[Søren Gjesse, 2014/02/12 13:16:35]

I don't see this in a previous example, maybe add

import 'dart:io';

main() {
  stdout.writeln('Hello, stdout');
  stderr.writeln('Hello, stderr');
}

[mem, 2014/02/12 19:17:07]

On 2014/02/12 13:16:35, Søren Gjesse wrote:

I was referring to the example above that starts up the `cat` process. I was
also referring to the getters for the Process instance not for the top-level
ones. Maybe I misunderstood the difference. Are they the same thing?

mem
Done.

[Søren Gjesse, 2014/02/13 16:03:55]

It was just that there was the exit code example in between.

Also they are not the same thing, and I think the change is fine.

+ *
+ * ## 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 
+ * 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
    * the range [0..255]. If the process was terminated due to a signal
@@ skipping 302 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";
   }
 }