Update DeltaProgram API and documentation.

pkg/front_end/lib/incremental_kernel_generator.dart

 // Copyright (c) 2017, 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.
 
 import 'dart:async';
 
 import 'package:front_end/src/base/processed_options.dart';
 import 'package:front_end/src/incremental_kernel_generator_impl.dart';
 import 'package:kernel/kernel.dart';
 
 import 'compiler_options.dart';
 
 /// Represents the difference between "old" and "new" states of a program.
 ///
 /// Not intended to be implemented or extended by clients.
 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.
 }
 
 /// Interface for generating an initial kernel representation of a program and
 /// keeping it up to date as incremental changes are made.
 ///
 /// This class maintains an internal "previous program state"; each
 /// time [computeDelta] is called, it updates the previous program state and
 /// produces a representation of what has changed.  When there are few changes,
@@ skipping 61 matching lines @@
 
   /// Remove all source files from the set of valid sources.  This guarantees
   /// that all files will be re-read on the next call to [computeDelta].
   ///
   /// Note that this does not erase the previous program state; the next time
   /// [computeDelta] is called, if parts of the program are discovered to be
   /// unchanged, parts of the previous program state will still be re-used to
   /// speed up compilation.
   void invalidateAll();
 }