Add documentation saying that String.fromEnvironment etc. must behave consistently.

AAll calls to those constructors must behave as if there is a single consistent
environment backing them.
This will force compilers to reject programs where that wouldn't be the case,
which is possible if doing modular compilation with different settings.

If a library doesn't check the environment, it doesn't matter whether the
environment was declared differently, the requirement is only that when actually checking,
the values must be consistent.

Bug: dart-lang/language#304
Change-Id: Ie52ecc3ea49ed87297fab92e5e7bb6d9f96a495d
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/184467
Commit-Queue: Lasse R.H. Nielsen <[email protected]>
Reviewed-by: Sigmund Cherem <[email protected]>
Reviewed-by: Leaf Petersen <[email protected]>
Reviewed-by: Erik Ernst <[email protected]>

Author: lrhn

sdk/lib/core/bool.dart

@@ -36,6 +36,11 @@ class bool {
   /// ```dart
   /// const isLoggingOn = (const String.fromEnvironment("logging") == "on");
   /// ```
+  ///
+  /// The string value, or lack of a value, associated with a [name]
+  /// must be consistent across all calls to [String.fromEnvironment],
+  /// [int.fromEnvironment], `bool.fromEnvironment` and [bool.hasEnvironment]
+  /// in a single program.
   // The .fromEnvironment() constructors are special in that we do not want
   // users to call them using "new". We prohibit that by giving them bodies
   // that throw, even though const constructors are not allowed to have bodies.
@@ -66,6 +71,11 @@ class bool {
   ///     ? String.fromEnvironment("logging")
   ///     : null;
   /// ```
+  ///
+  /// The string value, or lack of a value, associated with a [name]
+  /// must be consistent across all calls to [String.fromEnvironment],
+  /// [int.fromEnvironment], [bool.fromEnvironment] and `bool.hasEnvironment`
+  /// in a single program.
   // The .hasEnvironment() constructor is special in that we do not want
   // users to call them using "new". We prohibit that by giving them bodies
   // that throw, even though const constructors are not allowed to have bodies.

sdk/lib/core/int.dart

@@ -32,6 +32,11 @@ abstract class int extends num {
   /// ```
   /// const int.fromEnvironment("defaultPort", defaultValue: 80)
   /// ```
+  ///
+  /// The string value, or lack of a value, associated with a [name]
+  /// must be consistent across all calls to [String.fromEnvironment],
+  /// `int.fromEnvironment`, [bool.fromEnvironment] and [bool.hasEnvironment]
+  /// in a single program.
   // The .fromEnvironment() constructors are special in that we do not want
   // users to call them using "new". We prohibit that by giving them bodies
   // that throw, even though const constructors are not allowed to have bodies.

sdk/lib/core/string.dart

@@ -146,6 +146,11 @@ abstract class String implements Comparable<String>, Pattern {
   ///     ? String.fromEnvironment("maybeDeclared")
   ///     : null;
   /// ```
+  ///
+  /// The string value, or lack of a value, associated with a [name]
+  /// must be consistent across all calls to `String.fromEnvironment`,
+  /// [int.fromEnvironment], [bool.fromEnvironment] and [bool.hasEnvironment]
+  /// in a single program.
   // The .fromEnvironment() constructors are special in that we do not want
   // users to call them using "new". We prohibit that by giving them bodies
   // that throw, even though const constructors are not allowed to have bodies.