Update DeltaProgram API and documentation.

pkg/front_end/lib/incremental_kernel_generator.dart

Index: pkg/front_end/lib/incremental_kernel_generator.dart
diff --git a/pkg/front_end/lib/incremental_kernel_generator.dart b/pkg/front_end/lib/incremental_kernel_generator.dart
index 637f640b1c730da93b1a6d401c955e9488b70e50..f1094f1e46d937e456c20fa20fde8b22d42edd3c 100644
--- a/pkg/front_end/lib/incremental_kernel_generator.dart
+++ b/pkg/front_end/lib/incremental_kernel_generator.dart
@@ -16,11 +16,20 @@ import 'compiler_options.dart';
 class DeltaProgram {
   /// The new state of the program.
   ///
-  /// Libraries whose kernel representation is known to be unchanged since the
-  /// last [DeltaProgram] are not included.
-  final Map<Uri, Program> newState;
+  /// It includes full kernels for changed libraries and for libraries that
+  /// are affected by the transitive change of API in the changed libraries.
+  ///
+  /// For VM reload purposes we need to provide also full kernels for the
+  /// libraries that are transitively imported by the library with `main()`
+  /// and transitively import a changed library.
+  /// TODO(scheglov) With `main()` or entry point URI?

[Siggi Cherem (dart-lang), 2017/05/08 22:49:36]

for the purpose of the implementation here - anything reachable from the entry
[source] URI given to the incremental generator. For hot-reload we'll always
give you the source that contains "main" as [source].

+  ///
+  /// Also includes outlines for the transitive closure of libraries that are

[Siggi Cherem (dart-lang), 2017/05/08 22:49:36]

Using the terminology from earlier today, I'd rephrase this as:

  Also includes external references to other libraries 
  that were not modified or affected.

I want to especially keep it open that it may not include the entire outline of
those libraries.

+  /// referenced by previously specified changed, affected or VM-required
+  /// libraries.
+  final Program newProgram;
 
-  DeltaProgram(this.newState);
+  DeltaProgram(this.newProgram);

[Siggi Cherem (dart-lang), 2017/05/08 22:49:36]

Let's add a TODO saying that [Program] will become a different type?

This is where I expect we'll have the "Bundle of modular builds".

The concept of "bundles" doesn't exist in Kernel yet, but what we want is a way
to put together separately compiled libraries without having to link references
by hand here.

In a way I think this why we had a Map<Uri, Program>. Each entry in the Map was
the modular-build of a library. The "Program" would have a null mainMethod, and
would mainly have the kernel of a library and external references to all other
libraries. Some libraries would be mentioned several times, but only one of the
entries in the Map would have the body of that library (all other references are
"external").

 
   /// TODO(paulberry): add information about libraries that were removed.
 }