Update DDC Readme

pkg/dev_compiler/README.md

Index: pkg/dev_compiler/README.md
diff --git a/pkg/dev_compiler/README.md b/pkg/dev_compiler/README.md
index 7d3a3dd0b22a6516179c38f1359b2edc593e0e9f..71448e5a37f93abbf9003a0cede9eda3e6817988 100644
--- a/pkg/dev_compiler/README.md
+++ b/pkg/dev_compiler/README.md
@@ -2,30 +2,60 @@ dev_compiler
 ============
 
 [![Build Status](https://travis-ci.org/dart-lang/sdk.svg?branch=master)](https://travis-ci.org/dart-lang/sdk)
-[![Coverage Status](https://coveralls.io/repos/dart-lang/sdk/badge.svg?branch=master)](https://coveralls.io/r/dart-lang/sdk)
 
-The Dart Dev Compiler (DDC) is an **experimental** development tool and transpiler.  It is at a very early stage today.  Its aims include the following:
+The Dart Dev Compiler (DDC) is a fast, modular compiler that generates modern JavaScript (EcmaScript 6).  Its primary use today to support fast, iterative development of Dart for web applications on Chrome and other modern browers.  

[Bob Nystrom, 2017/06/05 21:50:51]

"today to" -> "today is to".

I don't think "Dart for web" reads as a single noun for most people, so the end
of the sentence is a little awkward. Maybe:

"Its primary use today is to support fast, iterative development of Dart web
applications for Chrome and other modern browers."

[vsm, 2017/06/05 22:03:21]

Done.

 
-- A static checker based on stricter-than-standard-Dart type rules.
-- A modular Dart-to-ES6 transpiler for Dart programs that statically check.
+Most users will use DDC via [pub](https://webdev.dartlang.org/tools/pub/pub-serve).  It will be supported by pub starting with the Dart 1.24 release.

[Bob Nystrom, 2017/06/05 21:50:51]

"will be" -> "is".

[vsm, 2017/06/05 22:03:21]

Done.

 
-DDC attempts to map to idiomatic EcmaScript 6 (ES6) as cleanly as possible.  To do this while cohering to Dart semantics, DDC relies heavily on static type information, static checking, and runtime assertions.
+# Soundness and Restrictions
 
-DDC is intended to support a very [large subset](https://github.com/dart-lang/sdk/blob/master/pkg/dev_compiler/STRONG_MODE.md) of Dart.  If a program does not statically check, DDC will not result in valid generated code.  Our goal is that a program execution (of a valid program) that runs without triggering runtime assertions should run the same on other Dart platforms under checked mode or production mode.
+DDC is built upon Dart's new [strong mode](STRONG_MODE.md) type system.  It only compiles programs that statically type check (i.e., no strong mode errors).  It leverages static type checking to generate simpler, readable, and more idiomatic code with fewer runtime checks.  In general, DDC is able to provide stronger type guarantees - i.e., *soundness* - than traditional Dart checked mode with significantly fewer runtime checks.
 
-DDC does support untyped Dart code, but it will typically result in less readable and less efficient ES6 output.
+With strong mode, DDC is stricter than traditional Dart production mode or checked mode.  Running existing Dart code on DDC will generally require fixing both static and runtime type errors.  
 
-DDC has the following project goals:
+For example, although the following snippet will run in production or checked mode, it will fail to compile with DDC:
 
-- Effective static checking and error detection.
-- A debugging solution for all modern browsers.
-- Readable output.
-- Fast, modular compilation of Dart code.
-- Easy use of generated code from JavaScript.
+```dart
+  var list = ["hello", "world"];  // Inferred as List<String> in strong mode
+  List<int> list2 = list;  // Static type error: incompatible types

[Bob Nystrom, 2017/06/05 21:50:50]

Nit: Indentation isn't needed here.

[vsm, 2017/06/05 22:03:21]

Done.

+```
 
-DDC is still in a very early stage as highlighted by our choice of ES6.  ES6 itself is in active development across all modern browsers, but at various stages of support:
-[kangax.github.io/compat-table/es6](https://kangax.github.io/compat-table/es6/).
+On the other hand, the following snippet - which tries to mask the type error via casts - will compile with DDC, but fail with a runtime type error.
+
+```dart
+  var list = ["hello", "world"];
+  List<Object> list2 = list;  // Generics are covariant.  No runtime check required.
+  List<int> list3 = list2;  // Implicit runtime downcast triggers error

[Bob Nystrom, 2017/06/05 21:50:51]

Nit: Add "." at end of comment.

[vsm, 2017/06/05 22:03:21]

Done.

+```  
+
+See the [strong mode documentation](STRONG_MODE.md) for more details.
+
+# Modularity
+
+DDC provides fast, incremental compilation based on standard JavaScript modules.  Unlike Dart2JS, DDC does not require an entire Dart application.  Instead, it operates modularly: it compiles a set of Dart files into a JavaScript module.  A DDC compilation step requires a set of input Dart files and a set of *summaries* of dependencies.  It performs modular type checking as part of this compilation step, and, if the input type checks, it generates a JavaScript module (e.g., [*ES6*](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import), [*AMD*](https://github.com/amdjs/amdjs-api/blob/master/AMD.md), or [*CommonJS*](https://nodejs.org/docs/latest/api/modules.html).  The browser (i.e., the JavaScript runtime) loads and links the generated modules when running the application.  
+During development, a compilation step only needs to be rerun if the Dart files or summaries it relies upon change.  For most changes, only a very small part of your code will require recompilation.  Morever, modules that are unchanged can be cached in the browser.
+
+Most users will invoke DDC indirectly via [pub](https://webdev.dartlang.org/tools/pub/pub-serve).  Pub will compute module structure and build steps automatically and invoke DDC accordingly.  Pub configures DDC to use AMD modules and uses the standard [AMD `require.js` loader](http://requirejs.org/) to bootstrap and load the application.

[Bob Nystrom, 2017/06/05 21:50:51]

"will invoke" -> "invoke".

"will compute" -> "computes".

[vsm, 2017/06/05 22:03:21]

Done.

+
+More advanced users may want to configure or invoke DDC directly.  In general, the mapping of Dart files to JS modules is flexible.  The key requirement is that module dependences (i.e., `require` in AMD or CommonJS or `import` in ES6) must be acyclic.  In practice, this means that individual Dart libraries cannot each be mapped to a corresponding JS module (as Dart imports can be cyclic).  See the [usage document](USAGE.md) for more details.

[Bob Nystrom, 2017/06/05 21:50:51]

Maybe "can be" -> "can be and often are".

[vsm, 2017/06/05 22:03:21]

Done.

 
-We are targeting the subset of ES6 supported in Chrome.
+# EcmaScript 6
 
-To try out DDC and/or give feedback, please read our [usage](https://github.com/dart-lang/sdk/blob/master/pkg/dev_compiler/USAGE.md) page.
+DDC attempts to map Dart to idiomatic EcmaScript 6 (ES6) as cleanly as possible, and it relies heavily on static typing to do this.  In general, where Dart concepts map directly to ES6, DDC will generate code accordingly.  For example, Dart classes are mapped to ES6 classes, Dart fields to ES6 properties, Dart getters/setters to ES6 getters/setters, Dart methods to ES6 methods, and so on.  In most cases, names will be preserved and calling conventions will be natural JavaScript ones.

[Bob Nystrom, 2017/06/05 21:50:51]

"will be" -> "are".

[Bob Nystrom, 2017/06/05 21:50:51]

"will generate" -> "generates".

[vsm, 2017/06/05 22:03:21]

Done.

[vsm, 2017/06/05 22:03:21]

Done.

+
+There are some import caveats where Dart concepts do not map directly:
+
+- *Libraries*.  Multiple Dart libraries are mapped to a single JS module.  Each library appears as a first class object in the generated JS module, with its top-level symbols as members.  We currently use a heuristic (based upon file paths) to ensure unique naming of generated library objects.
+- *Generics*.  Dart generics are *reified*, i.e., they are preserved at runtime.  Generic classes are mapped to factories that, given one or more type parameters, return an actual ES6 class (e.g., `HashMap$(core.String, core.int)` produces a class that represents a HashMap from strings to ints).  Similarly, generic methods are mapped to factories that, given one or more type parameters, return a method.  
+- *Dynamic*.  DDC supports dynamically typed code (i.e., Dart's `dynamic` type), but it will typically generate less readable and less efficient ES6 output as many type checks must be deferred to runtime.  All dynamic operations are invoked via runtime helper code.
+- *Constructors*.  Dart supports multiple, named constructors for a given class with a different initialization order for fields.  In general, these are mapped to static methods on the generated ES6 class.
+- *Private members*.  Dart maps private members (e.g., private fields or methods) to ES6 symbols.  For example, `a._x` may map to `a[_x]` where `_x` is a symbol only defined in the scope of the generated library.
+- *Scoping*.  Dart scoping rules and reserved words are slightly different than JavaScript.  While we try to preserve names wherever possible, in certain cases, we may be required to rename.

[Bob Nystrom, 2017/06/05 21:50:51]

"may be" -> "are".

[vsm, 2017/06/05 22:03:21]

Done.

+
+In general, the current conventions (i.e., the Application Binary Interface or ABI in compiler terminology) should not be considered stable.  We reserve the right to change these in the future.
+
+# Browser support
+
+DDC currently supports Chrome stable (though users have had success running on FireFox and Safari).  In the near future, we expect to run all common modern browsers that support ES6.  ES6 itself is in active development across all modern browsers, but at advanced stages of support:

[Bob Nystrom, 2017/06/05 21:50:50]

"run all" -> "target all".

[vsm, 2017/06/05 22:03:21]

Done.

+
+[kangax.github.io/compat-table/es6](https://kangax.github.io/compat-table/es6/).