Issue 8742. Preserve leading line comments during java2dart translation.

pkg/analyzer/lib/src/generated/engine.dart

 // Copyright (c) 2014, 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.
 
 // This code was auto-generated, is not intended to be edited, and is subject to
 // significant change. Please see the README file for more information.
 
 library engine;
 
 import 'java_core.dart';
@@ skipping 76 matching lines @@
    * The logger that should receive information about errors within the analysis engine.
    */
   Logger _logger = Logger.NULL;
 
   /**
    * Create a new context in which analysis can be performed.
    *
    * @return the analysis context that was created
    */
   AnalysisContext createAnalysisContext() {
+    //
+    // If instrumentation is ignoring data, return an uninstrumented analysis context.
+    //
     if (Instrumentation.isNullLogger) {
       return new DelegatingAnalysisContextImpl();
     }
     return new InstrumentedAnalysisContextImpl.con1(new DelegatingAnalysisContextImpl());
   }
 
   /**
    * Return the logger that should receive information about errors within the analysis engine.
    *
    * @return the logger that should receive information about errors within the analysis engine
@@ skipping 2079 matching lines @@
    *
    * @param state the state to which the data is being transitioned
    * @param currentValue the value of the flags before the transition
    * @param bitMask the mask used to access the bit whose state is being set
    * @return the value of the data that should be kept in the cache
    */
   int updatedValue2(CacheState state, int currentValue, int bitIndex) {
     if (identical(state, CacheState.VALID)) {
       throw new IllegalArgumentException("Use setValue() to set the state to VALID");
     } else if (identical(state, CacheState.IN_PROCESS)) {
+      //
+      // We can leave the current value in the cache for any 'get' methods to access.
+      //
       return currentValue;
     }
     return BooleanArray.set2(currentValue, bitIndex, false);
   }
 }
 
 /**
  * Instances of the class `ResolutionState` represent the information produced by resolving
  * a compilation unit as part of a specific library.
  */
@@ skipping 699 matching lines @@
    *
    * @param state the state to which the data is being transitioned
    * @param currentValue the value of the data before the transition
    * @param defaultValue the value to be used if the current value is to be removed from the cache
    * @return the value of the data that should be kept in the cache
    */
   Object updatedValue(CacheState state, Object currentValue, Object defaultValue) {
     if (identical(state, CacheState.VALID)) {
       throw new IllegalArgumentException("Use setValue() to set the state to VALID");
     } else if (identical(state, CacheState.IN_PROCESS)) {
+      //
+      // We can leave the current value in the cache for any 'get' methods to access.
+      //
       return currentValue;
     }
     return defaultValue;
   }
 
   /**
    * Write a textual representation of this entry to the given builder. The result will only be used
    * for debugging purposes.
    *
    * @param builder the builder to which the text should be written
@@ skipping 159 matching lines @@
 
   /**
    * Initialize a newly created analysis context.
    */
   AnalysisContextImpl() : super() {
     _resultRecorder = new AnalysisContextImpl_AnalysisTaskResultRecorder(this);
     _cache = new AnalysisCache(AnalysisOptionsImpl.DEFAULT_CACHE_SIZE, new AnalysisContextImpl_ContextRetentionPolicy(this));
   }
 
   void addSourceInfo(Source source, SourceEntry info) {
+    // This implementation assumes that the access to the cache does not need to be synchronized
+    // because no other object can have access to this context while this method is being invoked.
     _cache.put(source, info);
   }
 
   void applyChanges(ChangeSet changeSet) {
     if (changeSet.isEmpty) {
       return;
     }
     {
+      //
+      // First, compute the list of sources that have been removed.
+      //
       List<Source> removedSources = new List<Source>.from(changeSet.removed3);
       for (SourceContainer container in changeSet.removedContainers) {
         addSourcesInContainer(removedSources, container);
       }
+      //
+      // Then determine which cached results are no longer valid.
+      //
       bool addedDartSource = false;
       for (Source source in changeSet.added3) {
         if (sourceAvailable(source)) {
           addedDartSource = true;
         }
       }
       for (Source source in changeSet.changed3) {
         sourceChanged(source);
       }
       for (Source source in removedSources) {
         sourceRemoved(source);
       }
       if (addedDartSource) {
+        // TODO(brianwilkerson) This is hugely inefficient, but we need to re-analyze any libraries
+        // that might have been referencing the not-yet-existing source that was just added. Longer
+        // term we need to keep track of which libraries are referencing non-existing sources and
+        // only re-analyze those libraries.
         for (MapEntry<Source, SourceEntry> mapEntry in _cache.entrySet()) {
           SourceEntry sourceEntry = mapEntry.getValue();
           if (!mapEntry.getKey().isInSystemLibrary && sourceEntry is DartEntry) {
             DartEntryImpl dartCopy = sourceEntry.writableCopy;
             dartCopy.invalidateAllResolutionInformation();
             mapEntry.setValue(dartCopy);
           }
         }
       }
     }
@@ skipping 130 matching lines @@
   ResolvableHtmlUnit computeResolvableHtmlUnit(Source source) {
     HtmlEntry htmlEntry = getReadableHtmlEntry(source);
     if (htmlEntry == null) {
       throw new AnalysisException.con1("computeResolvableHtmlUnit invoked for non-HTML file: ${source.fullName}");
     }
     htmlEntry = cacheHtmlParseData(source, htmlEntry, HtmlEntry.PARSED_UNIT);
     HtmlUnit unit = htmlEntry.getValue(HtmlEntry.PARSED_UNIT);
     if (unit == null) {
       throw new AnalysisException.con1("Internal error: computeResolvableHtmlUnit could not parse ${source.fullName}");
     }
+    // If the unit is ever modified by resolution then we will need to create a copy of it.
     return new ResolvableHtmlUnit(htmlEntry.modificationTime, unit);
   }
 
   AnalysisContext extractContext(SourceContainer container) => extractContextInto(container, AnalysisEngine.instance.createAnalysisContext() as InternalAnalysisContext);
 
   InternalAnalysisContext extractContextInto(SourceContainer container, InternalAnalysisContext newContext) {
     List<Source> sourcesToRemove = new List<Source>();
     {
+      // Move sources in the specified directory to the new context
       for (MapEntry<Source, SourceEntry> entry in _cache.entrySet()) {
         Source source = entry.getKey();
         if (container.contains(source)) {
           sourcesToRemove.add(source);
           newContext.addSourceInfo(source, entry.getValue().writableCopy);
         }
       }
     }
     return newContext;
   }
 
   AnalysisOptions get analysisOptions => _options;
 
   Element getElement(ElementLocation location) {
+    // TODO(brianwilkerson) This should not be a "get" method.
     try {
       List<String> components = (location as ElementLocationImpl).components;
       Source librarySource = computeSourceFromEncoding(components[0]);
       ElementImpl element = computeLibraryElement(librarySource) as ElementImpl;
       for (int i = 1; i < components.length; i++) {
         if (element == null) {
           return null;
         }
         element = element.getChild(components[i]);
       }
@@ skipping 57 matching lines @@
 
   SourceKind getKindOf(Source source) {
     SourceEntry sourceEntry = getReadableSourceEntry(source);
     if (sourceEntry == null) {
       return SourceKind.UNKNOWN;
     }
     return sourceEntry.kind;
   }
 
   List<Source> get launchableClientLibrarySources {
+    // TODO(brianwilkerson) This needs to filter out libraries that do not reference dart:html,
+    // either directly or indirectly.
     List<Source> sources = new List<Source>();
     {
       for (MapEntry<Source, SourceEntry> entry in _cache.entrySet()) {
         Source source = entry.getKey();
         SourceEntry sourceEntry = entry.getValue();
         if (identical(sourceEntry.kind, SourceKind.LIBRARY) && !source.isInSystemLibrary) {
+          //          DartEntry dartEntry = (DartEntry) sourceEntry;
+          //          if (dartEntry.getValue(DartEntry.IS_LAUNCHABLE) && dartEntry.getValue(DartEntry.IS_CLIENT)) {
           sources.add(source);
         }
       }
     }
     return new List.from(sources);
   }
 
   List<Source> get launchableServerLibrarySources {
+    // TODO(brianwilkerson) This needs to filter out libraries that reference dart:html, either
+    // directly or indirectly.
     List<Source> sources = new List<Source>();
     {
       for (MapEntry<Source, SourceEntry> entry in _cache.entrySet()) {
         Source source = entry.getKey();
         SourceEntry sourceEntry = entry.getValue();
         if (identical(sourceEntry.kind, SourceKind.LIBRARY) && !source.isInSystemLibrary) {
+          //          DartEntry dartEntry = (DartEntry) sourceEntry;
+          //          if (dartEntry.getValue(DartEntry.IS_LAUNCHABLE) && !dartEntry.getValue(DartEntry.IS_CLIENT)) {
           sources.add(source);
         }
       }
     }
     return new List.from(sources);
   }
 
   List<Source> getLibrariesContaining(Source source) {
     {
       SourceEntry sourceEntry = _cache.get(source);
@@ skipping 49 matching lines @@
 
   LineInfo getLineInfo(Source source) {
     SourceEntry sourceEntry = getReadableSourceEntry(source);
     if (sourceEntry != null) {
       return sourceEntry.getValue(SourceEntry.LINE_INFO);
     }
     return null;
   }
 
   Namespace getPublicNamespace(LibraryElement library) {
+    // TODO(brianwilkerson) Rename this to not start with 'get'. Note that this is not part of the
+    // API of the interface.
     Source source = library.definingCompilationUnit.source;
     DartEntry dartEntry = getReadableDartEntry(source);
     if (dartEntry == null) {
       return null;
     }
     Namespace namespace = null;
     if (identical(dartEntry.getValue(DartEntry.ELEMENT), library)) {
       namespace = dartEntry.getValue(DartEntry.PUBLIC_NAMESPACE);
     }
     if (namespace == null) {
       NamespaceBuilder builder = new NamespaceBuilder();
       namespace = builder.createPublicNamespace(library);
       {
         dartEntry = getReadableDartEntry(source);
         if (dartEntry == null) {
           AnalysisEngine.instance.logger.logError3(new AnalysisException.con1("A Dart file became a non-Dart file: ${source.fullName}"));
           return null;
         }
         if (identical(dartEntry.getValue(DartEntry.ELEMENT), library)) {
           DartEntryImpl dartCopy = getReadableDartEntry(source).writableCopy;
           dartCopy.setValue(DartEntry.PUBLIC_NAMESPACE, namespace);
           _cache.put(source, dartCopy);
         }
       }
     }
     return namespace;
   }
 
   Namespace getPublicNamespace2(Source source) {
+    // TODO(brianwilkerson) Rename this to not start with 'get'. Note that this is not part of the
+    // API of the interface.
     DartEntry dartEntry = getReadableDartEntry(source);
     if (dartEntry == null) {
       return null;
     }
     Namespace namespace = dartEntry.getValue(DartEntry.PUBLIC_NAMESPACE);
     if (namespace == null) {
       LibraryElement library = computeLibraryElement(source);
       if (library == null) {
         return null;
       }
@@ skipping 61 matching lines @@
    * Return a list of the sources that would be processed by [performAnalysisTask]. This
    * method duplicates, and must therefore be kept in sync with, [getNextTaskAnalysisTask].
    * This method is intended to be used for testing purposes only.
    *
    * @return a list of the sources that would be processed by [performAnalysisTask]
    */
   List<Source> get sourcesNeedingProcessing {
     Set<Source> sources = new Set<Source>();
     {
       bool hintsEnabled = _options.hint;
+      //
+      // Look for priority sources that need to be analyzed.
+      //
       for (Source source in _priorityOrder) {
         getSourcesNeedingProcessing2(source, _cache.get(source), true, hintsEnabled, sources);
       }
+      //
+      // Look for non-priority sources that need to be analyzed.
+      //
       for (MapEntry<Source, SourceEntry> entry in _cache.entrySet()) {
         getSourcesNeedingProcessing2(entry.getKey(), entry.getValue(), false, hintsEnabled, sources);
       }
     }
     return new List<Source>.from(sources);
   }
 
   AnalysisContentStatistics get statistics {
     AnalysisContentStatisticsImpl statistics = new AnalysisContentStatisticsImpl();
     {
       for (MapEntry<Source, SourceEntry> mapEntry in _cache.entrySet()) {
         SourceEntry entry = mapEntry.getValue();
         if (entry is DartEntry) {
           Source source = mapEntry.getKey();
           DartEntry dartEntry = entry;
           SourceKind kind = dartEntry.getValue(DartEntry.SOURCE_KIND);
+          // get library independent values
           statistics.putCacheItem(dartEntry, DartEntry.PARSE_ERRORS);
           statistics.putCacheItem(dartEntry, DartEntry.PARSED_UNIT);
           statistics.putCacheItem(dartEntry, DartEntry.SOURCE_KIND);
           statistics.putCacheItem(dartEntry, SourceEntry.LINE_INFO);
           if (identical(kind, SourceKind.LIBRARY)) {
             statistics.putCacheItem(dartEntry, DartEntry.ELEMENT);
             statistics.putCacheItem(dartEntry, DartEntry.EXPORTED_LIBRARIES);
             statistics.putCacheItem(dartEntry, DartEntry.IMPORTED_LIBRARIES);
             statistics.putCacheItem(dartEntry, DartEntry.INCLUDED_PARTS);
             statistics.putCacheItem(dartEntry, DartEntry.IS_CLIENT);
             statistics.putCacheItem(dartEntry, DartEntry.IS_LAUNCHABLE);
           }
+          // get library-specific values
           List<Source> librarySources = getLibrariesContaining(source);
           for (Source librarySource in librarySources) {
             statistics.putCacheItem2(dartEntry, librarySource, DartEntry.HINTS);
             statistics.putCacheItem2(dartEntry, librarySource, DartEntry.RESOLUTION_ERRORS);
             statistics.putCacheItem2(dartEntry, librarySource, DartEntry.RESOLVED_UNIT);
             statistics.putCacheItem2(dartEntry, librarySource, DartEntry.VERIFICATION_ERRORS);
           }
         }
       }
     }
@@ skipping 34 matching lines @@
   }
 
   void mergeContext(AnalysisContext context) {
     if (context is InstrumentedAnalysisContextImpl) {
       context = (context as InstrumentedAnalysisContextImpl).basis;
     }
     if (context is! AnalysisContextImpl) {
       return;
     }
     {
+      // TODO(brianwilkerson) This does not lock against the other context's cacheLock.
       for (MapEntry<Source, SourceEntry> entry in (context as AnalysisContextImpl)._cache.entrySet()) {
         Source newSource = entry.getKey();
         SourceEntry existingEntry = getReadableSourceEntry(newSource);
         if (existingEntry == null) {
+          // TODO(brianwilkerson) Decide whether we really need to copy the info.
           _cache.put(newSource, entry.getValue().writableCopy);
         } else {
         }
       }
     }
   }
 
   CompilationUnit parseCompilationUnit(Source source) => getDartParseData2(source, DartEntry.PARSED_UNIT, null);
 
   HtmlUnit parseHtmlUnit(Source source) => getHtmlParseData(source, HtmlEntry.PARSED_UNIT, null);
 
   AnalysisResult performAnalysisTask() {
     int getStart = JavaSystem.currentTimeMillis();
     AnalysisTask task = nextTaskAnalysisTask;
     int getEnd = JavaSystem.currentTimeMillis();
     if (task == null) {
       return new AnalysisResult(getChangeNotices(true), getEnd - getStart, null, -1);
     }
+    //System.out.println(task);
     int performStart = JavaSystem.currentTimeMillis();
     try {
       task.perform(_resultRecorder);
     } on AnalysisException catch (exception) {
       if (exception.cause is! JavaIOException) {
         AnalysisEngine.instance.logger.logError2("Internal error while performing the task: ${task}", exception);
       }
     }
     int performEnd = JavaSystem.currentTimeMillis();
     return new AnalysisResult(getChangeNotices(false), getEnd - getStart, task.runtimeType.toString(), performEnd - performStart);
   }
 
   void recordLibraryElements(Map<Source, LibraryElement> elementMap) {
     {
       Source htmlSource = _sourceFactory.forUri(DartSdk.DART_HTML);
       for (MapEntry<Source, LibraryElement> entry in getMapEntrySet(elementMap)) {
         Source librarySource = entry.getKey();
         LibraryElement library = entry.getValue();
+        //
+        // Cache the element in the library's info.
+        //
         DartEntry dartEntry = getReadableDartEntry(librarySource);
         if (dartEntry != null) {
           DartEntryImpl dartCopy = dartEntry.writableCopy;
           recordElementData(dartCopy, library, htmlSource);
           _cache.put(librarySource, dartCopy);
         }
       }
     }
   }
 
@@ skipping 11 matching lines @@
     return parseHtmlUnit(htmlSource);
   }
 
   void set analysisOptions(AnalysisOptions options) {
     {
       bool needsRecompute = this._options.analyzeFunctionBodies != options.analyzeFunctionBodies || this._options.dart2jsHint != options.dart2jsHint || (this._options.hint && !options.hint) || this._options.preserveComments != options.preserveComments;
       int cacheSize = options.cacheSize;
       if (this._options.cacheSize != cacheSize) {
         this._options.cacheSize = cacheSize;
         _cache.maxCacheSize = cacheSize;
+        //
+        // Cap the size of the priority list to being less than the cache size. Failure to do so can
+        // result in an infinite loop in performAnalysisTask() because re-caching one AST structure
+        // can cause another priority source's AST structure to be flushed.
+        //
         int maxPriorityOrderSize = cacheSize - _PRIORITY_ORDER_SIZE_DELTA;
         if (_priorityOrder.length > maxPriorityOrderSize) {
           List<Source> newPriorityOrder = new List<Source>(maxPriorityOrderSize);
           JavaSystem.arraycopy(_priorityOrder, 0, newPriorityOrder, 0, maxPriorityOrderSize);
           _priorityOrder = newPriorityOrder;
         }
       }
       this._options.analyzeFunctionBodies = options.analyzeFunctionBodies;
       this._options.dart2jsHint = options.dart2jsHint;
       this._options.hint = options.hint;
       this._options.incremental = options.incremental;
       this._options.preserveComments = options.preserveComments;
       if (needsRecompute) {
         invalidateAllResolutionInformation();
       }
     }
   }
 
   void set analysisPriorityOrder(List<Source> sources) {
     {
       if (sources == null || sources.isEmpty) {
         _priorityOrder = Source.EMPTY_ARRAY;
       } else {
         while (sources.remove(null)) {
         }
         if (sources.isEmpty) {
           _priorityOrder = Source.EMPTY_ARRAY;
         }
+        //
+        // Cap the size of the priority list to being less than the cache size. Failure to do so can
+        // result in an infinite loop in performAnalysisTask() because re-caching one AST structure
+        // can cause another priority source's AST structure to be flushed.
+        //
         int count = Math.min(sources.length, _options.cacheSize - _PRIORITY_ORDER_SIZE_DELTA);
         _priorityOrder = new List<Source>(count);
         for (int i = 0; i < count; i++) {
           _priorityOrder[i] = sources[i];
         }
       }
     }
   }
 
   void setChangedContents(Source source, String contents, int offset, int oldLength, int newLength) {
@@ skipping 61 matching lines @@
    * @param task the task that was performed
    * @return an entry containing the computed results
    * @throws AnalysisException if the results could not be recorded
    */
   DartEntry recordResolveDartLibraryTaskResults(ResolveDartLibraryTask task) {
     LibraryResolver resolver = task.libraryResolver;
     AnalysisException thrownException = task.exception;
     DartEntry unitEntry = null;
     Source unitSource = task.unitSource;
     if (resolver != null) {
+      //
+      // The resolver should only be null if an exception was thrown before (or while) it was
+      // being created.
+      //
       Set<Library> resolvedLibraries = resolver.resolvedLibraries;
       if (resolvedLibraries == null) {
+        //
+        // The resolved libraries should only be null if an exception was thrown during resolution.
+        //
         unitEntry = getReadableDartEntry(unitSource);
         if (unitEntry == null) {
           throw new AnalysisException.con1("A Dart file became a non-Dart file: ${unitSource.fullName}");
         }
         DartEntryImpl dartCopy = unitEntry.writableCopy;
         dartCopy.recordResolutionError();
         dartCopy.exception = thrownException;
         _cache.put(unitSource, dartCopy);
         if (thrownException != null) {
           throw thrownException;
         }
         return dartCopy;
       }
       {
         if (allModificationTimesMatch(resolvedLibraries)) {
           Source htmlSource = sourceFactory.forUri(DartSdk.DART_HTML);
           RecordingErrorListener errorListener = resolver.errorListener;
           for (Library library in resolvedLibraries) {
             Source librarySource = library.librarySource;
             for (Source source in library.compilationUnitSources) {
               CompilationUnit unit = library.getAST(source);
               List<AnalysisError> errors = errorListener.getErrors2(source);
               LineInfo lineInfo = getLineInfo(source);
               DartEntry dartEntry = _cache.get(source) as DartEntry;
               int sourceTime = source.modificationStamp;
               if (dartEntry.modificationTime != sourceTime) {
+                // The source has changed without the context being notified. Simulate notification.
                 sourceChanged(source);
                 dartEntry = getReadableDartEntry(source);
                 if (dartEntry == null) {
                   throw new AnalysisException.con1("A Dart file became a non-Dart file: ${source.fullName}");
                 }
               }
               DartEntryImpl dartCopy = dartEntry.writableCopy;
               if (thrownException == null) {
                 dartCopy.setValue(SourceEntry.LINE_INFO, lineInfo);
                 dartCopy.setState(DartEntry.PARSED_UNIT, CacheState.FLUSHED);
@@ skipping 16 matching lines @@
             }
           }
         } else {
           for (Library library in resolvedLibraries) {
             for (Source source in library.compilationUnitSources) {
               DartEntry dartEntry = getReadableDartEntry(source);
               if (dartEntry != null) {
                 int resultTime = library.getModificationTime(source);
                 DartEntryImpl dartCopy = dartEntry.writableCopy;
                 if (thrownException == null || resultTime >= 0) {
+                  //
+                  // The analysis was performed on out-of-date sources. Mark the cache so that the
+                  // sources will be re-analyzed using the up-to-date sources.
+                  //
                   dartCopy.recordResolutionNotInProcess();
                 } else {
+                  //
+                  // We could not determine whether the sources were up-to-date or out-of-date. Mark
+                  // the cache so that we won't attempt to re-analyze the sources until there's a
+                  // good chance that we'll be able to do so without error.
+                  //
                   dartCopy.recordResolutionError();
                 }
                 dartCopy.exception = thrownException;
                 _cache.put(source, dartCopy);
                 if (source == unitSource) {
                   unitEntry = dartCopy;
                 }
               }
             }
           }
@@ skipping 37 matching lines @@
    * @return `true` if we should record the results of the resolution
    * @throws AnalysisException if any of the modification times could not be determined (this should
    *           not happen)
    */
   bool allModificationTimesMatch(Set<Library> resolvedLibraries) {
     bool allTimesMatch = true;
     for (Library library in resolvedLibraries) {
       for (Source source in library.compilationUnitSources) {
         DartEntry dartEntry = getReadableDartEntry(source);
         if (dartEntry == null) {
+          // This shouldn't be possible because we should never have performed the task if the
+          // source didn't represent a Dart file, but check to be safe.
           throw new AnalysisException.con1("Internal error: attempting to reolve non-Dart file as a Dart file: ${source.fullName}");
         }
         int sourceTime = source.modificationStamp;
         int resultTime = library.getModificationTime(source);
         if (sourceTime != resultTime) {
+          // The source has changed without the context being notified. Simulate notification.
           sourceChanged(source);
           allTimesMatch = false;
         }
       }
     }
     return allTimesMatch;
   }
 
   /**
    * Given a source for a Dart file and the library that contains it, return a cache entry in which
    * the data represented by the given descriptor is available. This method assumes that the data
    * can be produced by generating hints for the library if the data is not already cached.
    *
    * @param unitSource the source representing the Dart file
    * @param librarySource the source representing the library containing the Dart file
    * @param dartEntry the cache entry associated with the Dart file
    * @param descriptor the descriptor representing the data to be returned
    * @return a cache entry containing the required data
    * @throws AnalysisException if data could not be returned because the source could not be parsed
    */
   DartEntry cacheDartHintData(Source unitSource, Source librarySource, DartEntry dartEntry, DataDescriptor descriptor) {
+    //
+    // Check to see whether we already have the information being requested.
+    //
     CacheState state = dartEntry.getState2(descriptor, librarySource);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
+      //
+      // If not, compute the information. Unless the modification date of the source continues to
+      // change, this loop will eventually terminate.
+      //
       dartEntry = new GenerateDartHintsTask(this, getLibraryElement(librarySource)).perform(_resultRecorder) as DartEntry;
       state = dartEntry.getState2(descriptor, librarySource);
     }
     return dartEntry;
   }
 
   /**
    * Given a source for a Dart file, return a cache entry in which the data represented by the given
    * descriptor is available. This method assumes that the data can be produced by parsing the
    * source if it is not already cached.
    *
    * @param source the source representing the Dart file
    * @param dartEntry the cache entry associated with the Dart file
    * @param descriptor the descriptor representing the data to be returned
    * @return a cache entry containing the required data
    * @throws AnalysisException if data could not be returned because the source could not be
    *           resolved
    */
   DartEntry cacheDartParseData(Source source, DartEntry dartEntry, DataDescriptor descriptor) {
     if (identical(descriptor, DartEntry.PARSED_UNIT)) {
       CompilationUnit unit = dartEntry.anyParsedCompilationUnit;
       if (unit != null) {
         return dartEntry;
       }
     }
+    //
+    // Check to see whether we already have the information being requested.
+    //
     CacheState state = dartEntry.getState(descriptor);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
+      //
+      // If not, compute the information. Unless the modification date of the source continues to
+      // change, this loop will eventually terminate.
+      //
       dartEntry = new ParseDartTask(this, source).perform(_resultRecorder) as DartEntry;
       state = dartEntry.getState(descriptor);
     }
     return dartEntry;
   }
 
   /**
    * Given a source for a Dart file and the library that contains it, return a cache entry in which
    * the data represented by the given descriptor is available. This method assumes that the data
    * can be produced by resolving the source in the context of the library if it is not already
    * cached.
    *
    * @param unitSource the source representing the Dart file
    * @param librarySource the source representing the library containing the Dart file
    * @param dartEntry the cache entry associated with the Dart file
    * @param descriptor the descriptor representing the data to be returned
    * @return a cache entry containing the required data
    * @throws AnalysisException if data could not be returned because the source could not be parsed
    */
   DartEntry cacheDartResolutionData(Source unitSource, Source librarySource, DartEntry dartEntry, DataDescriptor descriptor) {
+    //
+    // Check to see whether we already have the information being requested.
+    //
     CacheState state = (identical(descriptor, DartEntry.ELEMENT)) ? dartEntry.getState(descriptor) : dartEntry.getState2(descriptor, librarySource);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
+      //
+      // If not, compute the information. Unless the modification date of the source continues to
+      // change, this loop will eventually terminate.
+      //
+      // TODO(brianwilkerson) As an optimization, if we already have the element model for the
+      // library we can use ResolveDartUnitTask to produce the resolved AST structure much faster.
       dartEntry = new ResolveDartLibraryTask(this, unitSource, librarySource).perform(_resultRecorder) as DartEntry;
       state = (identical(descriptor, DartEntry.ELEMENT)) ? dartEntry.getState(descriptor) : dartEntry.getState2(descriptor, librarySource);
     }
     return dartEntry;
   }
 
   /**
    * Given a source for a Dart file and the library that contains it, return a cache entry in which
    * the data represented by the given descriptor is available. This method assumes that the data
    * can be produced by verifying the source in the given library if the data is not already cached.
    *
    * @param unitSource the source representing the Dart file
    * @param librarySource the source representing the library containing the Dart file
    * @param dartEntry the cache entry associated with the Dart file
    * @param descriptor the descriptor representing the data to be returned
    * @return a cache entry containing the required data
    * @throws AnalysisException if data could not be returned because the source could not be parsed
    */
   DartEntry cacheDartVerificationData(Source unitSource, Source librarySource, DartEntry dartEntry, DataDescriptor descriptor) {
+    //
+    // Check to see whether we already have the information being requested.
+    //
     CacheState state = dartEntry.getState2(descriptor, librarySource);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
+      //
+      // If not, compute the information. Unless the modification date of the source continues to
+      // change, this loop will eventually terminate.
+      //
       dartEntry = new GenerateDartErrorsTask(this, unitSource, getLibraryElement(librarySource)).perform(_resultRecorder) as DartEntry;
       state = dartEntry.getState2(descriptor, librarySource);
     }
     return dartEntry;
   }
 
   /**
    * Given a source for an HTML file, return a cache entry in which all of the data represented by
    * the given descriptors is available. This method assumes that the data can be produced by
    * parsing the source if it is not already cached.
    *
    * @param source the source representing the HTML file
    * @param htmlEntry the cache entry associated with the HTML file
    * @param descriptor the descriptor representing the data to be returned
    * @return a cache entry containing the required data
    * @throws AnalysisException if data could not be returned because the source could not be
    *           resolved
    */
   HtmlEntry cacheHtmlParseData(Source source, HtmlEntry htmlEntry, DataDescriptor descriptor) {
+    //
+    // Check to see whether we already have the information being requested.
+    //
     CacheState state = htmlEntry.getState(descriptor);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
+      //
+      // If not, compute the information. Unless the modification date of the source continues to
+      // change, this loop will eventually terminate.
+      //
       htmlEntry = new ParseHtmlTask(this, source).perform(_resultRecorder) as HtmlEntry;
       state = htmlEntry.getState(descriptor);
     }
     return htmlEntry;
   }
 
   /**
    * Given a source for an HTML file, return a cache entry in which the the data represented by the
    * given descriptor is available. This method assumes that the data can be produced by resolving
    * the source if it is not already cached.
    *
    * @param source the source representing the HTML file
    * @param dartEntry the cache entry associated with the HTML file
    * @param descriptor the descriptor representing the data to be returned
    * @return a cache entry containing the required data
    * @throws AnalysisException if data could not be returned because the source could not be
    *           resolved
    */
   HtmlEntry cacheHtmlResolutionData(Source source, HtmlEntry htmlEntry, DataDescriptor descriptor) {
+    //
+    // Check to see whether we already have the information being requested.
+    //
     CacheState state = htmlEntry.getState(descriptor);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
+      //
+      // If not, compute the information. Unless the modification date of the source continues to
+      // change, this loop will eventually terminate.
+      //
       htmlEntry = new ResolveHtmlTask(this, source).perform(_resultRecorder) as HtmlEntry;
       state = htmlEntry.getState(descriptor);
     }
     return htmlEntry;
   }
 
   /**
    * Given the encoded form of a source, use the source factory to reconstitute the original source.
    *
    * @param encoding the encoded form of a source
@@ skipping 261 matching lines @@
 
   /**
    * Look through the cache for a task that needs to be performed. Return the task that was found,
    * or `null` if there is no more work to be done.
    *
    * @return the next task that needs to be performed
    */
   AnalysisTask get nextTaskAnalysisTask {
     {
       bool hintsEnabled = _options.hint;
+      //
+      // Look for incremental analysis
+      //
       if (_incrementalAnalysisCache != null && _incrementalAnalysisCache.hasWork()) {
         AnalysisTask task = new IncrementalAnalysisTask(this, _incrementalAnalysisCache);
         _incrementalAnalysisCache = null;
         return task;
       }
+      //
+      // Look for a priority source that needs to be analyzed.
+      //
       for (Source source in _priorityOrder) {
         AnalysisTask task = getNextTaskAnalysisTask2(source, _cache.get(source), true, hintsEnabled);
         if (task != null) {
           return task;
         }
       }
+      //
+      // Look for a non-priority source that needs to be analyzed.
+      //
       for (MapEntry<Source, SourceEntry> entry in _cache.entrySet()) {
         AnalysisTask task = getNextTaskAnalysisTask2(entry.getKey(), entry.getValue(), false, hintsEnabled);
         if (task != null) {
           return task;
         }
       }
       return null;
     }
   }
 
@@ skipping 41 matching lines @@
         if (libraryEntry is DartEntry) {
           CacheState elementState = libraryEntry.getState(DartEntry.ELEMENT);
           if (identical(elementState, CacheState.INVALID) || (isPriority && identical(elementState, CacheState.FLUSHED))) {
             DartEntryImpl libraryCopy = libraryEntry.writableCopy;
             libraryCopy.setState(DartEntry.ELEMENT, CacheState.IN_PROCESS);
             _cache.put(librarySource, libraryCopy);
             return new ResolveDartLibraryTask(this, source, librarySource);
           }
           CacheState resolvedUnitState = dartEntry.getState2(DartEntry.RESOLVED_UNIT, librarySource);
           if (identical(resolvedUnitState, CacheState.INVALID) || (isPriority && identical(resolvedUnitState, CacheState.FLUSHED))) {
+            //
+            // The commented out lines below are an optimization that doesn't quite work yet. The
+            // problem is that if the source was not resolved because it wasn't part of any library,
+            // then there won't be any elements in the element model that we can use to resolve it.
+            //
+            //LibraryElement libraryElement = libraryEntry.getValue(DartEntry.ELEMENT);
+            //if (libraryElement != null) {
             DartEntryImpl dartCopy = dartEntry.writableCopy;
             dartCopy.setState2(DartEntry.RESOLVED_UNIT, librarySource, CacheState.IN_PROCESS);
             _cache.put(source, dartCopy);
+            //return new ResolveDartUnitTask(this, source, libraryElement);
             return new ResolveDartLibraryTask(this, source, librarySource);
           }
           CacheState verificationErrorsState = dartEntry.getState2(DartEntry.VERIFICATION_ERRORS, librarySource);
           if (identical(verificationErrorsState, CacheState.INVALID) || (isPriority && identical(verificationErrorsState, CacheState.FLUSHED))) {
             LibraryElement libraryElement = libraryEntry.getValue(DartEntry.ELEMENT);
             if (libraryElement != null) {
               DartEntryImpl dartCopy = dartEntry.writableCopy;
               dartCopy.setState2(DartEntry.VERIFICATION_ERRORS, librarySource, CacheState.IN_PROCESS);
               _cache.put(source, dartCopy);
               return new GenerateDartErrorsTask(this, source, libraryElement);
@@ skipping 238 matching lines @@
 
   /**
    * In response to a change to at least one of the compilation units in the given library,
    * invalidate any results that are dependent on the result of resolving that library.
    *
    * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
    *
    * @param librarySource the source of the library being invalidated
    */
   void invalidateLibraryResolution(Source librarySource) {
+    // TODO(brianwilkerson) This could be optimized. There's no need to flush all of these caches if
+    // the public namespace hasn't changed, which will be a fairly common case. The question is
+    // whether we can afford the time to compute the namespace to look for differences.
     DartEntry libraryEntry = getReadableDartEntry(librarySource);
     if (libraryEntry != null) {
       List<Source> includedParts = libraryEntry.getValue(DartEntry.INCLUDED_PARTS);
       DartEntryImpl libraryCopy = libraryEntry.writableCopy;
       libraryCopy.invalidateAllResolutionInformation();
       libraryCopy.setState(DartEntry.INCLUDED_PARTS, CacheState.INVALID);
       _cache.put(librarySource, libraryCopy);
       for (Source partSource in includedParts) {
         SourceEntry partEntry = _cache.get(partSource);
         if (partEntry is DartEntry) {
@@ skipping 64 matching lines @@
    * @throws AnalysisException if the results could not be recorded
    */
   DartEntry recordGenerateDartErrorsTask(GenerateDartErrorsTask task) {
     Source source = task.source;
     Source librarySource = task.libraryElement.source;
     AnalysisException thrownException = task.exception;
     DartEntry dartEntry = null;
     {
       SourceEntry sourceEntry = _cache.get(source);
       if (sourceEntry is! DartEntry) {
+        // This shouldn't be possible because we should never have performed the task if the source
+        // didn't represent a Dart file, but check to be safe.
         throw new AnalysisException.con1("Internal error: attempting to verify non-Dart file as a Dart file: ${source.fullName}");
       }
       dartEntry = sourceEntry as DartEntry;
       _cache.accessed(source);
       int sourceTime = source.modificationStamp;
       int resultTime = task.modificationTime;
       if (sourceTime == resultTime) {
         if (dartEntry.modificationTime != sourceTime) {
+          // The source has changed without the context being notified. Simulate notification.
           sourceChanged(source);
           dartEntry = getReadableDartEntry(source);
           if (dartEntry == null) {
             throw new AnalysisException.con1("A Dart file became a non-Dart file: ${source.fullName}");
           }
         }
         DartEntryImpl dartCopy = dartEntry.writableCopy;
         if (thrownException == null) {
           dartCopy.setValue2(DartEntry.VERIFICATION_ERRORS, librarySource, task.errors);
           ChangeNoticeImpl notice = getNotice(source);
           notice.setErrors(dartCopy.allErrors, dartCopy.getValue(SourceEntry.LINE_INFO));
         } else {
           dartCopy.setState2(DartEntry.VERIFICATION_ERRORS, librarySource, CacheState.ERROR);
         }
         dartCopy.exception = thrownException;
         _cache.put(source, dartCopy);
         dartEntry = dartCopy;
       } else {
         DartEntryImpl dartCopy = dartEntry.writableCopy;
         if (thrownException == null || resultTime >= 0) {
+          //
+          // The analysis was performed on out-of-date sources. Mark the cache so that the source
+          // will be re-verified using the up-to-date sources.
+          //
           dartCopy.setState2(DartEntry.VERIFICATION_ERRORS, librarySource, CacheState.INVALID);
         } else {
+          //
+          // We could not determine whether the sources were up-to-date or out-of-date. Mark the
+          // cache so that we won't attempt to re-verify the source until there's a good chance
+          // that we'll be able to do so without error.
+          //
           dartCopy.setState2(DartEntry.VERIFICATION_ERRORS, librarySource, CacheState.ERROR);
         }
         dartCopy.exception = thrownException;
         _cache.put(source, dartCopy);
         dartEntry = dartCopy;
       }
     }
     if (thrownException != null) {
       throw thrownException;
     }
     return dartEntry;
   }
 
   /**
    * Record the results produced by performing a [GenerateDartHintsTask]. If the results were
    * computed from data that is now out-of-date, then the results will not be recorded.
    *
    * @param task the task that was performed
    * @return an entry containing the computed results
    * @throws AnalysisException if the results could not be recorded
    */
   DartEntry recordGenerateDartHintsTask(GenerateDartHintsTask task) {
     Source librarySource = task.libraryElement.source;
     AnalysisException thrownException = task.exception;
     DartEntry libraryEntry = null;
     Map<Source, TimestampedData<List<AnalysisError>>> hintMap = task.hintMap;
     if (hintMap == null) {
       {
+        // We don't have any information about which sources to mark as invalid other than the library
+        // source.
         SourceEntry sourceEntry = _cache.get(librarySource);
         if (sourceEntry is! DartEntry) {
+          // This shouldn't be possible because we should never have performed the task if the source
+          // didn't represent a Dart file, but check to be safe.
           throw new AnalysisException.con1("Internal error: attempting to generate hints for non-Dart file as a Dart file: ${librarySource.fullName}");
         }
         if (thrownException == null) {
           thrownException = new AnalysisException.con1("GenerateDartHintsTask returned a null hint map without throwing an exception: ${librarySource.fullName}");
         }
         DartEntryImpl dartCopy = (sourceEntry as DartEntry).writableCopy;
         dartCopy.setState2(DartEntry.HINTS, librarySource, CacheState.ERROR);
         dartCopy.exception = thrownException;
         _cache.put(librarySource, dartCopy);
       }
       throw thrownException;
     }
     for (MapEntry<Source, TimestampedData<List<AnalysisError>>> entry in getMapEntrySet(hintMap)) {
       Source unitSource = entry.getKey();
       TimestampedData<List<AnalysisError>> results = entry.getValue();
       {
         SourceEntry sourceEntry = _cache.get(unitSource);
         if (sourceEntry is! DartEntry) {
+          // This shouldn't be possible because we should never have performed the task if the source
+          // didn't represent a Dart file, but check to be safe.
           throw new AnalysisException.con1("Internal error: attempting to parse non-Dart file as a Dart file: ${unitSource.fullName}");
         }
         DartEntry dartEntry = sourceEntry as DartEntry;
         if (unitSource == librarySource) {
           libraryEntry = dartEntry;
         }
         _cache.accessed(unitSource);
         int sourceTime = unitSource.modificationStamp;
         int resultTime = results.modificationTime;
         if (sourceTime == resultTime) {
           if (dartEntry.modificationTime != sourceTime) {
+            // The source has changed without the context being notified. Simulate notification.
             sourceChanged(unitSource);
             dartEntry = getReadableDartEntry(unitSource);
             if (dartEntry == null) {
               throw new AnalysisException.con1("A Dart file became a non-Dart file: ${unitSource.fullName}");
             }
           }
           DartEntryImpl dartCopy = dartEntry.writableCopy;
           if (thrownException == null) {
             dartCopy.setValue2(DartEntry.HINTS, librarySource, results.data);
             ChangeNoticeImpl notice = getNotice(unitSource);
             notice.setErrors(dartCopy.allErrors, dartCopy.getValue(SourceEntry.LINE_INFO));
           } else {
             dartCopy.setState2(DartEntry.HINTS, librarySource, CacheState.ERROR);
           }
           dartCopy.exception = thrownException;
           _cache.put(unitSource, dartCopy);
           dartEntry = dartCopy;
         } else {
           if (identical(dartEntry.getState2(DartEntry.HINTS, librarySource), CacheState.IN_PROCESS)) {
             DartEntryImpl dartCopy = dartEntry.writableCopy;
             if (thrownException == null || resultTime >= 0) {
+              //
+              // The analysis was performed on out-of-date sources. Mark the cache so that the sources
+              // will be re-analyzed using the up-to-date sources.
+              //
               dartCopy.setState2(DartEntry.HINTS, librarySource, CacheState.INVALID);
             } else {
+              //
+              // We could not determine whether the sources were up-to-date or out-of-date. Mark the
+              // cache so that we won't attempt to re-analyze the sources until there's a good chance
+              // that we'll be able to do so without error.
+              //
               dartCopy.setState2(DartEntry.HINTS, librarySource, CacheState.ERROR);
             }
             dartCopy.exception = thrownException;
             _cache.put(unitSource, dartCopy);
             dartEntry = dartCopy;
           }
         }
       }
     }
     if (thrownException != null) {
@@ skipping 29 matching lines @@
    * @return an entry containing the computed results
    * @throws AnalysisException if the results could not be recorded
    */
   DartEntry recordParseDartTaskResults(ParseDartTask task) {
     Source source = task.source;
     AnalysisException thrownException = task.exception;
     DartEntry dartEntry = null;
     {
       SourceEntry sourceEntry = _cache.get(source);
       if (sourceEntry is! DartEntry) {
+        // This shouldn't be possible because we should never have performed the task if the source
+        // didn't represent a Dart file, but check to be safe.
         throw new AnalysisException.con1("Internal error: attempting to parse non-Dart file as a Dart file: ${source.fullName}");
       }
       dartEntry = sourceEntry as DartEntry;
       _cache.accessed(source);
       int sourceTime = source.modificationStamp;
       int resultTime = task.modificationTime;
       if (sourceTime == resultTime) {
         if (dartEntry.modificationTime != sourceTime) {
+          // The source has changed without the context being notified. Simulate notification.
           sourceChanged(source);
           dartEntry = getReadableDartEntry(source);
           if (dartEntry == null) {
             throw new AnalysisException.con1("A Dart file became a non-Dart file: ${source.fullName}");
           }
         }
         DartEntryImpl dartCopy = dartEntry.writableCopy;
         if (thrownException == null) {
           LineInfo lineInfo = task.lineInfo;
           dartCopy.setValue(SourceEntry.LINE_INFO, lineInfo);
           if (task.hasPartOfDirective() && !task.hasLibraryDirective()) {
             dartCopy.setValue(DartEntry.SOURCE_KIND, SourceKind.PART);
           } else {
             dartCopy.setValue(DartEntry.SOURCE_KIND, SourceKind.LIBRARY);
           }
           dartCopy.setValue(DartEntry.PARSED_UNIT, task.compilationUnit);
           dartCopy.setValue(DartEntry.PARSE_ERRORS, task.errors);
           dartCopy.setValue(DartEntry.EXPORTED_LIBRARIES, task.exportedSources);
           dartCopy.setValue(DartEntry.IMPORTED_LIBRARIES, task.importedSources);
           dartCopy.setValue(DartEntry.INCLUDED_PARTS, task.includedSources);
           ChangeNoticeImpl notice = getNotice(source);
           notice.setErrors(dartEntry.allErrors, lineInfo);
+          // Verify that the incrementally parsed and resolved unit in the incremental cache
+          // is structurally equivalent to the fully parsed unit
           _incrementalAnalysisCache = IncrementalAnalysisCache.verifyStructure(_incrementalAnalysisCache, source, task.compilationUnit);
         } else {
           dartCopy.recordParseError();
         }
         dartCopy.exception = thrownException;
         _cache.put(source, dartCopy);
         dartEntry = dartCopy;
       } else {
         DartEntryImpl dartCopy = dartEntry.writableCopy;
         if (thrownException == null || resultTime >= 0) {
+          //
+          // The analysis was performed on out-of-date sources. Mark the cache so that the sources
+          // will be re-analyzed using the up-to-date sources.
+          //
           dartCopy.recordParseNotInProcess();
         } else {
+          //
+          // We could not determine whether the sources were up-to-date or out-of-date. Mark the
+          // cache so that we won't attempt to re-analyze the sources until there's a good chance
+          // that we'll be able to do so without error.
+          //
           dartCopy.recordParseError();
         }
         dartCopy.exception = thrownException;
         _cache.put(source, dartCopy);
         dartEntry = dartCopy;
       }
     }
     if (thrownException != null) {
       throw thrownException;
     }
     return dartEntry;
   }
 
   /**
    * Record the results produced by performing a [ParseHtmlTask]. If the results were computed
    * from data that is now out-of-date, then the results will not be recorded.
    *
    * @param task the task that was performed
    * @return an entry containing the computed results
    * @throws AnalysisException if the results could not be recorded
    */
   HtmlEntry recordParseHtmlTaskResults(ParseHtmlTask task) {
     Source source = task.source;
     AnalysisException thrownException = task.exception;
     HtmlEntry htmlEntry = null;
     {
       SourceEntry sourceEntry = _cache.get(source);
       if (sourceEntry is! HtmlEntry) {
+        // This shouldn't be possible because we should never have performed the task if the source
+        // didn't represent an HTML file, but check to be safe.
         throw new AnalysisException.con1("Internal error: attempting to parse non-HTML file as a HTML file: ${source.fullName}");
       }
       htmlEntry = sourceEntry as HtmlEntry;
       _cache.accessed(source);
       int sourceTime = source.modificationStamp;
       int resultTime = task.modificationTime;
       if (sourceTime == resultTime) {
         if (htmlEntry.modificationTime != sourceTime) {
+          // The source has changed without the context being notified. Simulate notification.
           sourceChanged(source);
           htmlEntry = getReadableHtmlEntry(source);
           if (htmlEntry == null) {
             throw new AnalysisException.con1("An HTML file became a non-HTML file: ${source.fullName}");
           }
         }
         HtmlEntryImpl htmlCopy = (sourceEntry as HtmlEntry).writableCopy;
         if (thrownException == null) {
           LineInfo lineInfo = task.lineInfo;
           HtmlUnit unit = task.htmlUnit;
           htmlCopy.setValue(SourceEntry.LINE_INFO, lineInfo);
           htmlCopy.setValue(HtmlEntry.PARSED_UNIT, unit);
           htmlCopy.setValue(HtmlEntry.PARSE_ERRORS, task.errors);
           htmlCopy.setValue(HtmlEntry.REFERENCED_LIBRARIES, task.referencedLibraries);
           ChangeNoticeImpl notice = getNotice(source);
           notice.setErrors(htmlEntry.allErrors, lineInfo);
         } else {
           htmlCopy.recordParseError();
         }
         htmlCopy.exception = thrownException;
         _cache.put(source, htmlCopy);
         htmlEntry = htmlCopy;
       } else {
         HtmlEntryImpl htmlCopy = (sourceEntry as HtmlEntry).writableCopy;
         if (thrownException == null || resultTime >= 0) {
+          //
+          // The analysis was performed on out-of-date sources. Mark the cache so that the sources
+          // will be re-analyzed using the up-to-date sources.
+          //
           if (identical(htmlCopy.getState(SourceEntry.LINE_INFO), CacheState.IN_PROCESS)) {
             htmlCopy.setState(SourceEntry.LINE_INFO, CacheState.INVALID);
           }
           if (identical(htmlCopy.getState(HtmlEntry.PARSED_UNIT), CacheState.IN_PROCESS)) {
             htmlCopy.setState(HtmlEntry.PARSED_UNIT, CacheState.INVALID);
           }
           if (identical(htmlCopy.getState(HtmlEntry.REFERENCED_LIBRARIES), CacheState.IN_PROCESS)) {
             htmlCopy.setState(HtmlEntry.REFERENCED_LIBRARIES, CacheState.INVALID);
           }
         } else {
+          //
+          // We could not determine whether the sources were up-to-date or out-of-date. Mark the
+          // cache so that we won't attempt to re-analyze the sources until there's a good chance
+          // that we'll be able to do so without error.
+          //
           htmlCopy.setState(SourceEntry.LINE_INFO, CacheState.ERROR);
           htmlCopy.setState(HtmlEntry.PARSED_UNIT, CacheState.ERROR);
           htmlCopy.setState(HtmlEntry.REFERENCED_LIBRARIES, CacheState.ERROR);
         }
         htmlCopy.exception = thrownException;
         _cache.put(source, htmlCopy);
         htmlEntry = htmlCopy;
       }
     }
     if (thrownException != null) {
@@ skipping 11 matching lines @@
    * @throws AnalysisException if the results could not be recorded
    */
   SourceEntry recordResolveDartUnitTaskResults(ResolveDartUnitTask task) {
     Source unitSource = task.source;
     Source librarySource = task.librarySource;
     AnalysisException thrownException = task.exception;
     DartEntry dartEntry = null;
     {
       SourceEntry sourceEntry = _cache.get(unitSource);
       if (sourceEntry is! DartEntry) {
+        // This shouldn't be possible because we should never have performed the task if the source
+        // didn't represent a Dart file, but check to be safe.
         throw new AnalysisException.con1("Internal error: attempting to reolve non-Dart file as a Dart file: ${unitSource.fullName}");
       }
       dartEntry = sourceEntry as DartEntry;
       _cache.accessed(unitSource);
       int sourceTime = unitSource.modificationStamp;
       int resultTime = task.modificationTime;
       if (sourceTime == resultTime) {
         if (dartEntry.modificationTime != sourceTime) {
+          // The source has changed without the context being notified. Simulate notification.
           sourceChanged(unitSource);
           dartEntry = getReadableDartEntry(unitSource);
           if (dartEntry == null) {
             throw new AnalysisException.con1("A Dart file became a non-Dart file: ${unitSource.fullName}");
           }
         }
         DartEntryImpl dartCopy = dartEntry.writableCopy;
         if (thrownException == null) {
           dartCopy.setValue2(DartEntry.RESOLVED_UNIT, librarySource, task.resolvedUnit);
         } else {
           dartCopy.setState2(DartEntry.RESOLVED_UNIT, librarySource, CacheState.ERROR);
         }
         dartCopy.exception = thrownException;
         _cache.put(unitSource, dartCopy);
         dartEntry = dartCopy;
       } else {
         DartEntryImpl dartCopy = dartEntry.writableCopy;
         if (thrownException == null || resultTime >= 0) {
+          //
+          // The analysis was performed on out-of-date sources. Mark the cache so that the sources
+          // will be re-analyzed using the up-to-date sources.
+          //
           if (identical(dartCopy.getState(DartEntry.RESOLVED_UNIT), CacheState.IN_PROCESS)) {
             dartCopy.setState2(DartEntry.RESOLVED_UNIT, librarySource, CacheState.INVALID);
           }
         } else {
+          //
+          // We could not determine whether the sources were up-to-date or out-of-date. Mark the
+          // cache so that we won't attempt to re-analyze the sources until there's a good chance
+          // that we'll be able to do so without error.
+          //
           dartCopy.setState2(DartEntry.RESOLVED_UNIT, librarySource, CacheState.ERROR);
         }
         dartCopy.exception = thrownException;
         _cache.put(unitSource, dartCopy);
         dartEntry = dartCopy;
       }
     }
     if (thrownException != null) {
       throw thrownException;
     }
     return dartEntry;
   }
 
   /**
    * Record the results produced by performing a [ResolveHtmlTask]. If the results were
    * computed from data that is now out-of-date, then the results will not be recorded.
    *
    * @param task the task that was performed
    * @return an entry containing the computed results
    * @throws AnalysisException if the results could not be recorded
    */
   SourceEntry recordResolveHtmlTaskResults(ResolveHtmlTask task) {
     Source source = task.source;
     AnalysisException thrownException = task.exception;
     HtmlEntry htmlEntry = null;
     {
       SourceEntry sourceEntry = _cache.get(source);
       if (sourceEntry is! HtmlEntry) {
+        // This shouldn't be possible because we should never have performed the task if the source
+        // didn't represent an HTML file, but check to be safe.
         throw new AnalysisException.con1("Internal error: attempting to reolve non-HTML file as an HTML file: ${source.fullName}");
       }
       htmlEntry = sourceEntry as HtmlEntry;
       _cache.accessed(source);
       int sourceTime = source.modificationStamp;
       int resultTime = task.modificationTime;
       if (sourceTime == resultTime) {
         if (htmlEntry.modificationTime != sourceTime) {
+          // The source has changed without the context being notified. Simulate notification.
           sourceChanged(source);
           htmlEntry = getReadableHtmlEntry(source);
           if (htmlEntry == null) {
             throw new AnalysisException.con1("An HTML file became a non-HTML file: ${source.fullName}");
           }
         }
         HtmlEntryImpl htmlCopy = htmlEntry.writableCopy;
         if (thrownException == null) {
           htmlCopy.setValue(HtmlEntry.ELEMENT, task.element);
           htmlCopy.setValue(HtmlEntry.RESOLUTION_ERRORS, task.resolutionErrors);
           ChangeNoticeImpl notice = getNotice(source);
           notice.htmlUnit = task.resolvedUnit;
           notice.setErrors(htmlCopy.allErrors, htmlCopy.getValue(SourceEntry.LINE_INFO));
         } else {
           htmlCopy.recordResolutionError();
         }
         htmlCopy.exception = thrownException;
         _cache.put(source, htmlCopy);
         htmlEntry = htmlCopy;
       } else {
         HtmlEntryImpl htmlCopy = htmlEntry.writableCopy;
         if (thrownException == null || resultTime >= 0) {
+          //
+          // The analysis was performed on out-of-date sources. Mark the cache so that the sources
+          // will be re-analyzed using the up-to-date sources.
+          //
           if (identical(htmlCopy.getState(HtmlEntry.ELEMENT), CacheState.IN_PROCESS)) {
             htmlCopy.setState(HtmlEntry.ELEMENT, CacheState.INVALID);
           }
           if (identical(htmlCopy.getState(HtmlEntry.RESOLUTION_ERRORS), CacheState.IN_PROCESS)) {
             htmlCopy.setState(HtmlEntry.RESOLUTION_ERRORS, CacheState.INVALID);
           }
         } else {
+          //
+          // We could not determine whether the sources were up-to-date or out-of-date. Mark the
+          // cache so that we won't attempt to re-analyze the sources until there's a good chance
+          // that we'll be able to do so without error.
+          //
           htmlCopy.recordResolutionError();
         }
         htmlCopy.exception = thrownException;
         _cache.put(source, htmlCopy);
         htmlEntry = htmlCopy;
       }
     }
     if (thrownException != null) {
       throw thrownException;
     }
@@ skipping 22 matching lines @@
   }
 
   /**
    * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
    *
    * @param source the source that has been changed
    */
   void sourceChanged(Source source) {
     SourceEntry sourceEntry = _cache.get(source);
     if (sourceEntry == null || sourceEntry.modificationTime == source.modificationStamp) {
+      // Either we have removed this source, in which case we don't care that it is changed, or we
+      // have already invalidated the cache and don't need to invalidate it again.
       return;
     }
     if (sourceEntry is HtmlEntry) {
       HtmlEntryImpl htmlCopy = sourceEntry.writableCopy;
       htmlCopy.modificationTime = source.modificationStamp;
       htmlCopy.invalidateAllInformation();
       _cache.put(source, htmlCopy);
     } else if (sourceEntry is DartEntry) {
       List<Source> containingLibraries = getLibrariesContaining(source);
       Set<Source> librariesToInvalidate = new Set<Source>();
       for (Source containingLibrary in containingLibraries) {
         librariesToInvalidate.add(containingLibrary);
         for (Source dependentLibrary in getLibrariesDependingOn(containingLibrary)) {
           librariesToInvalidate.add(dependentLibrary);
         }
       }
       for (Source library in librariesToInvalidate) {
+        //    for (Source library : containingLibraries) {
         invalidateLibraryResolution(library);
       }
       DartEntryImpl dartCopy = sourceEntry.writableCopy;
       dartCopy.modificationTime = source.modificationStamp;
       dartCopy.invalidateAllInformation();
       _cache.put(source, dartCopy);
     }
   }
 
   /**
@@ skipping 438 matching lines @@
       return _sdkAnalysisContext.parseHtmlUnit(source);
     } else {
       return super.parseHtmlUnit(source);
     }
   }
 
   void recordLibraryElements(Map<Source, LibraryElement> elementMap) {
     if (elementMap.isEmpty) {
       return;
     }
+    // TODO(jwren) we are making the assumption here that the elementMap will have sources from only
+    // one library, while this is true with our use of the Analysis Engine, it is not required by
+    // the API, revisit to fix cases where the elementMap can have sources both in the sdk and other
+    // libraries
     Source source = new JavaIterator(elementMap.keys.toSet()).next();
     if (source.isInSystemLibrary) {
       _sdkAnalysisContext.recordLibraryElements(elementMap);
     } else {
       super.recordLibraryElements(elementMap);
     }
   }
 
   CompilationUnit resolveCompilationUnit(Source source, LibraryElement library) {
     if (source.isInSystemLibrary) {
@@ skipping 95 matching lines @@
    * @param oldContents the original source contents prior to this update (may be `null`)
    * @param newContents the new contents after this incremental change (not `null`)
    * @param offset the offset at which the change occurred
    * @param oldLength the length of the text being replaced
    * @param newLength the length of the replacement text
    * @param sourceEntry the cached entry for the given source or `null` if none
    * @return the cache used for incremental analysis or `null` if incremental analysis cannot
    *         be performed
    */
   static IncrementalAnalysisCache update(IncrementalAnalysisCache cache, Source source, String oldContents, String newContents, int offset, int oldLength, int newLength, SourceEntry sourceEntry) {
+    // Determine the cache resolved unit
     Source librarySource = null;
     CompilationUnit unit = null;
     if (sourceEntry is DartEntryImpl) {
       DartEntryImpl dartEntry = sourceEntry;
       List<Source> librarySources = dartEntry.librariesContaining;
       if (librarySources.length == 1) {
         librarySource = librarySources[0];
         if (librarySource != null) {
           unit = dartEntry.getValue2(DartEntry.RESOLVED_UNIT, librarySource);
         }
       }
     }
+    // Create a new cache if there is not an existing cache or the source is different
+    // or a new resolved compilation unit is available
     if (cache == null || cache.source != source || unit != null) {
       if (unit == null) {
         return null;
       }
       if (oldContents == null) {
         if (oldLength != 0) {
           return null;
         }
         oldContents = "${newContents.substring(0, offset)}${newContents.substring(offset + newLength)}";
       }
       return new IncrementalAnalysisCache(librarySource, source, unit, oldContents, newContents, offset, oldLength, newLength);
     }
+    // Update the existing cache if the change is contiguous
     if (cache._oldLength == 0 && cache._newLength == 0) {
       cache._offset = offset;
       cache._oldLength = oldLength;
       cache._newLength = newLength;
     } else {
       if (cache._offset > offset || offset > cache._offset + cache._newLength) {
         return null;
       }
       cache._newLength += newLength - oldLength;
     }
@@ skipping 1266 matching lines @@
   void internalPerform() {
     InternalAnalysisContext context = this.context;
     TimestampedData<CompilationUnit> data = context.internalResolveCompilationUnit(source, libraryElement);
     TimeCounter_TimeCounterHandle timeCounter = PerformanceStatistics.errors.start();
     try {
       _modificationTime = data.modificationTime;
       CompilationUnit unit = data.data;
       RecordingErrorListener errorListener = new RecordingErrorListener();
       ErrorReporter errorReporter = new ErrorReporter(errorListener, source);
       TypeProvider typeProvider = context.typeProvider;
+      //
+      // Use the ConstantVerifier to verify the use of constants. This needs to happen before using
+      // the ErrorVerifier because some error codes need the computed constant values.
+      //
       ConstantVerifier constantVerifier = new ConstantVerifier(errorReporter, typeProvider);
       unit.accept(constantVerifier);
+      //
+      // Use the ErrorVerifier to compute the rest of the errors.
+      //
       ErrorVerifier errorVerifier = new ErrorVerifier(errorReporter, libraryElement, typeProvider, new InheritanceManager(libraryElement));
       unit.accept(errorVerifier);
       _errors = errorListener.getErrors2(source);
     } finally {
       timeCounter.stop();
     }
   }
 }
 
 /**
@@ skipping 38 matching lines @@
     }
     return "generate Dart hints for ${librarySource.fullName}";
   }
 
   void internalPerform() {
     RecordingErrorListener errorListener = new RecordingErrorListener();
     List<CompilationUnitElement> parts = libraryElement.parts;
     int partCount = parts.length;
     List<CompilationUnit> compilationUnits = new List<CompilationUnit>(partCount + 1);
     Map<Source, TimestampedData<CompilationUnit>> timestampMap = new Map<Source, TimestampedData<CompilationUnit>>();
+    //
+    // Get all of the (fully resolved) compilation units that will be analyzed.
+    //
     Source unitSource = libraryElement.definingCompilationUnit.source;
     TimestampedData<CompilationUnit> resolvedUnit = getCompilationUnit(unitSource);
     timestampMap[unitSource] = resolvedUnit;
     CompilationUnit unit = resolvedUnit.data;
     if (unit == null) {
       throw new AnalysisException.con1("Internal error: GenerateDartHintsTask failed to access resolved compilation unit for ${unitSource.fullName}");
     }
     compilationUnits[0] = unit;
     for (int i = 0; i < partCount; i++) {
       unitSource = parts[i].source;
       resolvedUnit = getCompilationUnit(unitSource);
       timestampMap[unitSource] = resolvedUnit;
       unit = resolvedUnit.data;
       if (unit == null) {
         throw new AnalysisException.con1("Internal error: GenerateDartHintsTask failed to access resolved compilation unit for ${unitSource.fullName}");
       }
       compilationUnits[i + 1] = unit;
     }
+    //
+    // Analyze all of the units.
+    //
     HintGenerator hintGenerator = new HintGenerator(compilationUnits, context, errorListener);
     hintGenerator.generateForLibrary();
+    //
+    // Store the results.
+    //
     _hintMap = new Map<Source, TimestampedData<List<AnalysisError>>>();
     for (MapEntry<Source, TimestampedData<CompilationUnit>> entry in getMapEntrySet(timestampMap)) {
       Source source = entry.getKey();
       TimestampedData<CompilationUnit> unitData = entry.getValue();
       List<AnalysisError> errors = errorListener.getErrors2(source);
       _hintMap[source] = new TimestampedData<List<AnalysisError>>(unitData.modificationTime, errors);
     }
   }
 
   /**
@@ skipping 45 matching lines @@
    * @return the source
    */
   Source get source => cache != null ? cache.source : null;
 
   String get taskDescription => "incremental analysis ${(cache != null ? cache.source : "null")}";
 
   void internalPerform() {
     if (cache == null) {
       return;
     }
+    // Only handle small changes
     if (cache.oldLength > 0 || cache.newLength > 30) {
       return;
     }
+    // Produce an updated token stream
     CharacterReader reader = new CharSequenceReader(new CharSequence(cache.newContents));
     BooleanErrorListener errorListener = new BooleanErrorListener();
     IncrementalScanner scanner = new IncrementalScanner(cache.source, reader, errorListener);
     scanner.rescan(cache.resolvedUnit.beginToken, cache.offset, cache.oldLength, cache.newLength);
     if (errorListener.errorReported) {
       return;
     }
+    // Produce an updated AST
     IncrementalParser parser = new IncrementalParser(cache.source, scanner.tokenMap, AnalysisErrorListener.NULL_LISTENER);
     _updatedUnit = parser.reparse(cache.resolvedUnit, scanner.leftToken, scanner.rightToken, cache.offset, cache.offset + cache.oldLength);
+    // Update the resolution
     TypeProvider typeProvider = this.typeProvider;
     if (_updatedUnit != null && typeProvider != null) {
       CompilationUnitElement element = _updatedUnit.element;
       if (element != null) {
         LibraryElement library = element.library;
         if (library != null) {
           IncrementalResolver resolver = new IncrementalResolver(library, cache.source, typeProvider, errorListener);
           resolver.resolve(parser.updatedNode);
         }
       }
@@ skipping 153 matching lines @@
   String get taskDescription {
     if (source == null) {
       return "parse as dart null source";
     }
     return "parse as dart ${source.fullName}";
   }
 
   void internalPerform() {
     RecordingErrorListener errorListener = new RecordingErrorListener();
     List<Token> token = [null];
+    //
+    // Scan the contents of the file.
+    //
     Source_ContentReceiver receiver = new Source_ContentReceiver_ParseDartTask_internalPerform(this, errorListener, token);
     try {
       source.getContents(receiver);
     } on JavaException catch (exception) {
       _modificationTime = source.modificationStamp;
       throw new AnalysisException.con3(exception);
     }
     if (token[0] == null) {
       throw new AnalysisException.con1("Could not get contents for '${source.fullName}'");
     }
+    //
+    // Then parse the token stream.
+    //
     TimeCounter_TimeCounterHandle timeCounterParse = PerformanceStatistics.parse.start();
     try {
       Parser parser = new Parser(source, errorListener);
       parser.parseFunctionBodies = context.analysisOptions.analyzeFunctionBodies;
       _unit = parser.parseCompilationUnit(token[0]);
       _errors = errorListener.getErrors2(source);
       for (Directive directive in _unit.directives) {
         if (directive is ExportDirective) {
           Source exportSource = resolveSource(source, directive);
           if (exportSource != null) {
@@ skipping 383 matching lines @@
   }
 
   void internalPerform() {
     TypeProvider typeProvider = (_libraryElement.context as InternalAnalysisContext).typeProvider;
     ResolvableCompilationUnit resolvableUnit = context.computeResolvableCompilationUnit(source);
     _modificationTime = resolvableUnit.modificationTime;
     CompilationUnit unit = resolvableUnit.compilationUnit;
     if (unit == null) {
       throw new AnalysisException.con1("Internal error: computeResolvableCompilationUnit returned a value without a parsed Dart unit");
     }
+    //
+    // Resolve names in declarations.
+    //
     new DeclarationResolver().resolve(unit, find(_libraryElement, source));
+    //
+    // Resolve the type names.
+    //
     RecordingErrorListener errorListener = new RecordingErrorListener();
     TypeResolverVisitor typeResolverVisitor = new TypeResolverVisitor.con2(_libraryElement, source, typeProvider, errorListener);
     unit.accept(typeResolverVisitor);
+    //
+    // Resolve the rest of the structure
+    //
     InheritanceManager inheritanceManager = new InheritanceManager(_libraryElement);
     ResolverVisitor resolverVisitor = new ResolverVisitor.con2(_libraryElement, source, typeProvider, inheritanceManager, errorListener);
     unit.accept(resolverVisitor);
+    // TODO (jwren) Move this logic/ loop into the ResolverVisitor and then make the reportError protected again.
     for (ProxyConditionalAnalysisError conditionalCode in resolverVisitor.proxyConditionalAnalysisErrors) {
       if (conditionalCode.shouldIncludeErrorCode()) {
         resolverVisitor.reportError(conditionalCode.analysisError);
       }
     }
+    //
+    // Perform additional error checking.
+    //
     TimeCounter_TimeCounterHandle counterHandleErrors = PerformanceStatistics.errors.start();
     try {
       ErrorReporter errorReporter = new ErrorReporter(errorListener, source);
       ErrorVerifier errorVerifier = new ErrorVerifier(errorReporter, _libraryElement, typeProvider, inheritanceManager);
       unit.accept(errorVerifier);
       ConstantVerifier constantVerifier = new ConstantVerifier(errorReporter, typeProvider);
       unit.accept(constantVerifier);
     } finally {
       counterHandleErrors.stop();
     }
+    //
+    // Capture the results.
+    //
     _resolvedUnit = unit;
   }
 
   /**
    * Search the compilation units that are part of the given library and return the element
    * representing the compilation unit with the given source. Return `null` if there is no
    * such compilation unit.
    *
    * @param libraryElement the element representing the library being searched through
    * @param unitSource the source for the compilation unit whose element is to be returned
@@ skipping 78 matching lines @@
     return "resolve as html ${source.fullName}";
   }
 
   void internalPerform() {
     ResolvableHtmlUnit resolvableHtmlUnit = context.computeResolvableHtmlUnit(source);
     HtmlUnit unit = resolvableHtmlUnit.compilationUnit;
     if (unit == null) {
       throw new AnalysisException.con1("Internal error: computeResolvableHtmlUnit returned a value without a parsed HTML unit");
     }
     _modificationTime = resolvableHtmlUnit.modificationTime;
+    // build standard HTML element
     HtmlUnitBuilder builder = new HtmlUnitBuilder(context);
     _element = builder.buildHtmlElement2(source, _modificationTime, unit);
+    // resolve toolkit-specific features
     LineInfo lineInfo = context.getLineInfo(source);
 //    new AngularHtmlUnitResolver(context, builder.errorListener, source, lineInfo).resolve(unit);
+    // record all resolution errors
     _resolutionErrors = builder.errorListener.getErrors2(source);
+    // remember resolved unit
     _resolvedUnit = unit;
   }
 }
 
 /**
  * The interface `Logger` defines the behavior of objects that can be used to receive
  * information about errors within the analysis engine. Implementations usually write this
  * information to a file, but can also record the information for later use (such as during testing)
  * or even ignore the information.
  *
@@ skipping 53 matching lines @@
 
   void logError3(Exception exception) {
   }
 
   void logInformation(String message) {
   }
 
   void logInformation2(String message, Exception exception) {
   }
 }