Update documentation on .fromEnvironment. Make bool default be false.

sdk/lib/core/string.dart

 // Copyright (c) 2012, 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.core;
 
 /**
  * A sequence of characters.
  *
  * A string can be either single or multiline. Single line strings are
@@ skipping 107 matching lines @@
    *
    * Creating a String with half of a surrogate pair is legal but generally
    * discouraged.
    */
   factory String.fromCharCode(int charCode) {
     List<int> charCodes = new List<int>.filled(1, charCode);
     return new String.fromCharCodes(charCodes);
   }
 
   /**
-   * Returns the string for the given environment variable [name] or
-   * [defaultValue] if [name] is not present.
+   * Returns the string value of the environment declaration [name].
+   *
+   * Environment declarations are provided by the surrounding system compiling
+   * or running the Dart program. Declarations map a string key to a string
+   * value.
+   *
+   * If [name] is not declared in the environment, the result is instead
+   * [defaultValue].
+   *
+   * Example of getting a value:
+   *
+   *     const String.fromEnvironment("defaultFloo", defaultValue: "no floo")
+   *
+   * Example of checking whether a declaration is there at all:
+   *
+   *     var isDeclared = const String.fromEnvironment("maybeDeclared") != null;
    */
   external const factory String.fromEnvironment(String name,
                                                 {String defaultValue});
 
   /**
    * Gets the character (as a single-code-unit [String]) at the given [index].
    *
    * The returned string represents exactly one UTF-16 code unit, which may be
    * half of a surrogate pair. A single member of a surrogate pair is an
    * invalid UTF-16 string:
@@ skipping 516 matching lines @@
         _position = position - 1;
         _currentCodePoint = _combineSurrogatePair(prevCodeUnit, codeUnit);
         return true;
       }
     }
     _position = position;
     _currentCodePoint = codeUnit;
     return true;
   }
 }