Merge pull request #601 from dart-lang/doc-optional-features

Docs for no-implicit-casts and no-implicit-dynamic

Author: John Messerly

pkg/dev_compiler/doc/STATIC_SAFETY.md

@@ -416,6 +416,107 @@ code where a field definition in a subclass shadows the field
   allocated.  Users should prefer explicit getters and setters in such
   cases.  See [issue 52](https://github.com/dart-lang/dev_compiler/issues/52).
 
+## Optional Features
+
+### Disable implicit casts (experimental)
+
+This is an optional feature of strong mode. It disables implicit down casts. For example:
+
+```dart
+main() {
+  num n = 0.5;
+  int x = n; // error: invalid assignment
+  int y = n as int; // ok at compile time, might fail when run
+}
+```
+
+Casts from `dynamic` must be explicit as well:
+
+```dart
+main() {
+  dynamic d = 'hi';
+  int x = d; // error: invalid assignment
+  int y = d as int; // ok at compile time, might fail when run
+}
+```
+
+This option is experimental and may be changed or removed in the future. Feedback is appreciated! Contact us at our [mailing list](https://groups.google.com/a/dartlang.org/forum/#!forum/dev-compiler).
+Try it out in your project by editing .analysis_options:
+
+```yaml
+analyzer:
+  strong-mode:
+    implicit-casts: False
+```
+
+Or pass `--no-implicit-casts` to Dart Analyzer:
+
+```
+dartanalyzer --strong --no-implicit-casts my_app.dart
+```
+
+### Disable implicit dynamic (experimental)
+
+This is an optional feature of analyzer, intended primarily for use with strong mode's inference.
+It rejects implicit uses of `dynamic` that strong mode inference fails to fill in with a concrete type,
+ensuring that all types are either successfully inferred or explicitly written. For example:
+
+```dart
+main() {
+  var x; // error: implicit dynamic
+  var i = 123; // okay, inferred to be `int x`
+  dynamic y; // okay, declared as dynamic
+}
+```
+
+This also affects: parameters, return types, fields, creating objects with generic type, generic functions/methods, and
+supertypes:
+
+```dart
+// error: parameters and return types are implicit dynamic
+f(x) => x + 42;
+dynamic f(dynamic x) => x + 42; // okay
+int f(int x) => x + 42; // okay
+
+class C {
+  var f; // error: implicit dynamic field
+  dynamic f; // okay
+}
+
+main() {
+  var x = []; // error: implicit List<dynamic>
+  var y = [42]; // okay: List<int>
+  var z = <dynamic>[]; // okay: List<dynamic>
+  
+  T genericFn<T>() => null;
+  genericFn(); // error: implicit genericFn<dynamic>
+  genericFn<dynamic>(); // okay
+  int x = genericFn(); // okay, inferred genericFn<int>
+}
+
+// error: implicit supertype Iterable<dynamic>
+class C extends Iterable { /* ... */ }
+// okay
+class C extends Iterable<dynamic> { /* ... */ }
+```
+
+This feature is to prevent accidental use of `dynamic` in code that does not intend to use it.
+
+This option is experimental and may be changed or removed in the future. Feedback is appreciated! Contact us at our [mailing list](https://groups.google.com/a/dartlang.org/forum/#!forum/dev-compiler).
+Try it out in your project by editing .analysis_options:
+
+```yaml
+analyzer:
+  strong-mode:
+    implicit-dynamic: False
+```
+
+Or pass `--no-implicit-dynamic` to Dart Analyzer:
+
+```
+dartanalyzer --strong --no-implicit-dynamic my_app.dart
+```
+
 ### Open Items
 
 - Is / As restrictions: Dart's `is` and `as` checks are unsound for certain types