Clean up documentation of Platform in dart:io.

sdk/lib/io/platform.dart

Index: sdk/lib/io/platform.dart
diff --git a/sdk/lib/io/platform.dart b/sdk/lib/io/platform.dart
index 482898c8d01a007b68d5a8b9a7de8718301e28fb..1a592cde71a6f9c5c46a1e7deb7f05631c0a9e28 100644
--- a/sdk/lib/io/platform.dart
+++ b/sdk/lib/io/platform.dart
@@ -74,54 +74,56 @@ class Platform {
   static final _ansiSupported = _Platform.ansiSupported;
 
   /**
-   * Get the number of processors of the machine.
+   * The number of processors of the machine.
    */
   static int get numberOfProcessors => _numberOfProcessors;
 
   /**
-   * Get the path separator used by the operating system to separate
+   * Te path separator used by the operating system to separate

[jensj, 2017/03/20 07:42:30]

"The"?

[Lasse Reichstein Nielsen, 2017/04/04 07:25:15]

Done.

    * components in file paths.
    */
   static String get pathSeparator => _pathSeparator;
 
   /**
-   * Get a string (`linux`, `macos`, `windows`, `android`, or `ios`)
-   * representing the operating system.
+   * A string representing the operating system or platform.
    */
   static String get operatingSystem => _operatingSystem;
 
   /**
-   * Get the local hostname for the system.
+   * The local hostname for the system.
    */
   static String get localHostname => _localHostname;
 
   /**
-   * Returns true if the operating system is Linux.
+   * Whether the operating system is a version of [Linux](https://en.wikipedia.org/wiki/Linux).
+   *
+   * This value is `false` if the operating system is a specialized
+   * version of Linux that identifies itself by a different name, e.g., Android.

[floitsch, 2017/03/17 15:52:37]

don't use "e.g."

[Lasse Reichstein Nielsen, 2017/04/04 07:25:15]

Done.

    */
   static final bool isLinux = (_operatingSystem == "linux");
 
   /**
-   * Returns true if the operating system is OS X.
+   * Whether the operating system is a version of [macOS](https://en.wikipedia.org/wiki/MacOS).

[floitsch, 2017/03/17 15:52:37]

long line.

[Lasse Reichstein Nielsen, 2017/04/04 07:25:15]

Turns out that it works if you break the line before the "[".

    */
   static final bool isMacOS = (_operatingSystem == "macos");
 
   /**
-   * Returns true if the operating system is Windows.
+   * Whether the operating system is a version of [Microsoft Windows](https://en.wikipedia.org/wiki/Microsoft_Windows).

[floitsch, 2017/03/17 15:52:37]

long line.

    */
   static final bool isWindows = (_operatingSystem == "windows");
 
   /**
-   * Returns true if the operating system is Android.
+   * Whether the operating system is a version of [Android](https://en.wikipedia.org/wiki/Android_(operating_system)).

[floitsch, 2017/03/17 15:52:37]

long line.

    */
   static final bool isAndroid = (_operatingSystem == "android");
 
   /**
-   * Returns true if the operating system is iOS.
+   * Whether the operating system is a version of [iOS](https://en.wikipedia.org/wiki/IOS).

[floitsch, 2017/03/17 15:52:37]

long line.

    */
   static final bool isIOS = (_operatingSystem == "ios");
 
   /**
-   * Returns true if the operating system is Fuchsia
+   * Whether the operating system is a version of [Fuchsia](https://en.wikipedia.org/wiki/Google_Fuchsia).

[floitsch, 2017/03/17 15:52:37]

lon line.

    */
   static final bool isFuchsia = (_operatingSystem == "fuchsia");
 
@@ -134,23 +136,22 @@ class Platform {
   static final bool ansiSupported = _ansiSupported;
 
   /**
-   * Get the environment for this process.
+   * The environment for this process as a map from string key to string value.
    *
-   * The returned environment is an unmodifiable map which content is
-   * retrieved from the operating system on its first use.
+   * The map is unmodifiable,
+   * and its content is retrieved from the operating system on its first use.
    *
-   * Environment variables on Windows are case-insensitive. The map
-   * returned on Windows is therefore case-insensitive and will convert
-   * all keys to upper case. On other platforms the returned map is
-   * a standard case-sensitive map.
+   * Environment variables on Windows are case-insensitive,
+   * so on Windows the map is case-insensitive and will convert
+   * all keys to upper case.
+   * On other platforms, keys can be distinguished by case.
    */
   static Map<String, String> get environment => _Platform.environment;
 
   /**
-   * Returns the path of the executable used to run the script in this
-   * isolate.
+   * The path of the executable used to run the script in this isolate.
    *
-   * The path returned is the literal path used to run the script. This
+   * The path is the literal path used to run the script. This

[floitsch, 2017/03/17 15:52:37]

The literal path used to run the script.

[Lasse Reichstein Nielsen, 2017/04/04 07:25:15]

Done.

    * path might be relative or just be a name from which the executable
    * was found by searching the `PATH`.
    *
@@ -160,7 +161,7 @@ class Platform {
   static String get executable => _Platform.executable;
 
   /**
-   * Returns the path of the executable used to run the script in this
+   * The path of the executable used to run the script in this
    * isolate after it has been resolved by the OS.
    *
    * This is the absolute path, with all symlinks resolved, to the
@@ -169,55 +170,57 @@ class Platform {
   static String get resolvedExecutable => _Platform.resolvedExecutable;
 
   /**
-   * Returns the absolute URI of the script being run in this
-   * isolate.
+   * The absolute URI of the script being run in this isolate.
    *
    * If the script argument on the command line is relative,
    * it is resolved to an absolute URI before fetching the script, and
-   * this absolute URI is returned.
+   * that absolute URI is returned.
    *
    * URI resolution only does string manipulation on the script path, and this
    * may be different from the file system's path resolution behavior. For
    * example, a symbolic link immediately followed by '..' will not be
    * looked up.
    *
-   * If the executable environment does not support [script] an empty
-   * [Uri] is returned.
+   * If the executable environment does not support [script],
+   * the URI is empty.
    */
   static Uri get script => _Platform.script;
 
   /**
-   * Returns the flags passed to the executable used to run the script in this
-   * isolate. These are the command-line flags between the executable name
-   * and the script name. Each fetch of executableArguments returns a new
-   * List, containing the flags passed to the executable.
+   * The flags passed to the executable used to run the script in this isolate.
+   *
+   * These are the command-line flags to the executable that precedes
+   * the script name.
+   * Provides a new list every time the value is read.
    */
   static List<String> get executableArguments => _Platform.executableArguments;
 
   /**
-   * Returns the value of the `--package-root` flag passed to the executable
-   * used to run the script in this isolate.  This is the directory in which
-   * Dart packages are looked up.
+   * The `--package-root` flag passed to the executable used to run the script
+   * in this isolate.
+   *
+   * If present, it specifies the directory where Dart packages are looked up.
    *
-   * If there is no `--package-root` flag, `null` is returned.
+   * Is `null` if there is no `--package-root` flag.
    */
   static String get packageRoot => _Platform.packageRoot;
 
-/**
- * Returns the value of the `--packages` flag passed to the executable
- * used to run the script in this isolate. This is the configuration which
- * specifies how Dart packages are looked up.
- *
- * If there is no `--packages` flag, `null` is returned.
- */
+  /**
+   * The `--packages` flag passed to the executable used to run the script
+   * in this isolate.
+   *
+   * If present, it specifies a file describing how Dart packages are looked up.
+   *
+   * Is `null` if there is no `--packages` flag.
+   */
   static String get packageConfig => _Platform.packageConfig;
 
   /**
-   * Returns the version of the current Dart runtime.
+   * The version of the current Dart runtime.
    *
-   * The returned `String` is formatted as the
-   * [semver](http://semver.org) version string of the current dart
-   * runtime, possibly followed by whitespace and other version and
+   * The value is a [semantic versioning](http://semver.org)
+   * string representing the version of the current Dart runtime,
+   * possibly followed by whitespace and other version and
    * build details.
    */
   static String get version => _version;