Incremental resolution of updated DartDoc comments.

pkg/analyzer/lib/src/generated/incremental_resolver.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.
 
 library engine.incremental_resolver;
 
 import 'dart:collection';
 import 'dart:math' as math;
 
 import 'package:analyzer/src/generated/error_verifier.dart';
@@ skipping 601 matching lines @@
  * Instances of the class [IncrementalResolver] resolve the smallest portion of
  * an AST structure that we currently know how to resolve.
  */
 class IncrementalResolver {
   /**
    * The object used to access the types from the core library.
    */
   final TypeProvider _typeProvider;
 
   /**
-   * The element for the library containing the compilation unit being resolved.
-   */
-  final LibraryElement _definingLibrary;
-
-  /**
    * The element of the compilation unit being resolved.
    */
   final CompilationUnitElement _definingUnit;
 
   /**
+   * The element for the library containing the compilation unit being resolved.
+   */
+  LibraryElement _definingLibrary;
+
+  /**
    * The source representing the compilation unit being visited.
    */
-  final Source _source;
+  Source _source;
 
   /**
    * The offset of the changed contents.
    */
   final int _updateOffset;
 
   /**
    * The number of characters in the original contents that were replaced.
    */
   final int _updateOldLength;
 
   /**
    * The number of characters in the replacement text.
    */
   final int _updateNewLength;
 
   ResolutionContext _resolutionContext;
 
   List<AnalysisError> _resolveErrors = AnalysisError.NO_ERRORS;
   List<AnalysisError> _verifyErrors = AnalysisError.NO_ERRORS;
   List<AnalysisError> _hints = AnalysisError.NO_ERRORS;
 
   /**
    * Initialize a newly created incremental resolver to resolve a node in the
    * given source in the given library.
    */
-  IncrementalResolver(this._typeProvider, this._definingLibrary,
-      this._definingUnit, this._source, this._updateOffset, this._updateOldLength,
-      this._updateNewLength);
+  IncrementalResolver(this._typeProvider, this._definingUnit,
+      this._updateOffset, this._updateOldLength, this._updateNewLength) {
+    _definingLibrary = _definingUnit.library;
+    _source = _definingUnit.source;
+  }
 
   /**
    * Resolve [node], reporting any errors or warnings to the given listener.
    *
    * [node] - the root of the AST structure to be resolved.
    */
   void resolve(AstNode node) {
     AstNode rootNode = _findResolutionRoot(node);
     // update elements
     _updateElementNameOffsets(
@@ skipping 128 matching lines @@
       ResolverVisitor visitor = new ResolverVisitor.con3(
           _definingLibrary,
           _source,
           _typeProvider,
           _resolutionContext.scope,
           errorListener);
       if (_resolutionContext.enclosingClassDeclaration != null) {
         visitor.visitClassDeclarationIncrementally(
             _resolutionContext.enclosingClassDeclaration);
       }
+      if (node is Comment) {
+        visitor.resolveOnlyCommentInFunctionBody = true;
+        node = node.parent;
+      }
+      visitor.initForIncrementalResolution();
       node.accept(visitor);
     }
     // remember errors
     _resolveErrors = errorListener.getErrorsForSource(_source);
   }
 
   void _updateElements(AstNode node) {
     // build elements in node
     ElementHolder holder;
     _ElementsRestorer elementsRestorer = new _ElementsRestorer(node);
@@ skipping 103 matching lines @@
         int beginOffsetOld = math.min(firstOffsetOld, lastOffsetOld);
         int endOffsetOld = math.max(firstOffsetOld, lastOffsetOld);
         int beginOffsetNew = math.min(firstOffsetNew, lastOffsetNew);
         int endOffsetNew = math.max(firstOffsetNew, lastOffsetNew);
         // check for a whitespace only change
         if (identical(lastPair.oldToken, firstPair.oldToken) &&
             identical(lastPair.newToken, firstPair.newToken)) {
           _updateOffset = beginOffsetOld - 1;
           _updateEndOld = endOffsetOld;
           _updateDelta = newUnit.length - oldUnit.length;
+          if (firstPair.atComment && lastPair.atComment) {
+            _resolveComment(oldUnit, newUnit, firstPair);
+          }
           _shiftTokens(firstPair.oldToken, _updateDelta);
           IncrementalResolver._updateElementNameOffsets(
               oldUnit.element,
               _updateOffset,
               _updateDelta);
           _updateEntry();
           return true;
         }
-//        print('beginOffsetOld: $beginOffsetOld endOffsetOld: $endOffsetOld');
-//        print('beginOffsetNew: $beginOffsetNew endOffsetNew: $endOffsetNew');
         // Find nodes covering the "old" and "new" token ranges.
         AstNode oldNode =
             _findNodeCovering(oldUnit, beginOffsetOld, endOffsetOld);
         AstNode newNode =
             _findNodeCovering(newUnit, beginOffsetNew, endOffsetNew);
 //        print('oldNode: $oldNode');
 //        print('newNode: $newNode');
         // Try to find the smallest common node, a FunctionBody currently.
         {
           List<AstNode> oldParents = _getParents(oldNode);
@@ skipping 26 matching lines @@
 //        print('newNode: $newNode');
         // prepare update range
         _updateOffset = oldNode.offset;
         _updateEndOld = oldNode.end;
         _updateEndNew = newNode.end;
         _updateDelta = _updateEndNew - _updateEndOld;
         // replace node
         NodeReplacer.replace(oldNode, newNode);
         // update token references
         {
-          Token oldBeginToken = oldNode.beginToken;
+          Token oldBeginToken = _getBeginTokenNotComment(oldNode);
+          Token newBeginToken = _getBeginTokenNotComment(newNode);
           if (oldBeginToken.previous.type == TokenType.EOF) {
-            oldUnit.beginToken = newNode.beginToken;
+            oldUnit.beginToken = newBeginToken;
           } else {
-            oldBeginToken.previous.setNext(newNode.beginToken);
+            oldBeginToken.previous.setNext(newBeginToken);
           }
           newNode.endToken.setNext(oldNode.endToken.next);
           _shiftTokens(oldNode.endToken.next, _updateDelta);
         }
         // perform incremental resolution
         CompilationUnitElement oldUnitElement = oldUnit.element;
         IncrementalResolver incrementalResolver = new IncrementalResolver(
             _typeProvider,
-            oldUnitElement.library,
             oldUnitElement,
-            oldUnitElement.source,
             _updateOffset,
             oldNode.length,
             newNode.length);
         incrementalResolver.resolve(newNode);
         _newResolveErrors = incrementalResolver._resolveErrors;
         _newVerifyErrors = incrementalResolver._verifyErrors;
         _newHints = incrementalResolver._hints;
         _updateEntry();
 //        print('Successfully incrementally resolved.');
         return true;
       }
     } catch (e) {
       // TODO(scheglov) find a way to log these exceptions
 //      print(e);
 //      print(st);
     }
     return false;
   }
 
   CompilationUnit _parseUnit(String code) {
     Token token = _scan(code);
     RecordingErrorListener errorListener = new RecordingErrorListener();
     Parser parser = new Parser(_unitSource, errorListener);
     CompilationUnit unit = parser.parseCompilationUnit(token);
     _newParseErrors = errorListener.errors;
     return unit;
   }
 
+  void _resolveComment(CompilationUnit oldUnit, CompilationUnit newUnit,
+      _TokenPair firstPair) {
+    Token oldToken = firstPair.oldToken;
+    int offset = oldToken.precedingComments.offset;
+    Comment oldComment = _findNodeCovering(oldUnit, offset, offset);
+    Comment newComment = _findNodeCovering(newUnit, offset, offset);
+    _updateOffset = offset + 1;
+    // replace node
+    NodeReplacer.replace(oldComment, newComment);
+    // update token references
+    _setPrecedingComments(oldToken, newComment.tokens.first);
+    // resolve references in the comment
+    CompilationUnitElement oldUnitElement = oldUnit.element;
+    IncrementalResolver incrementalResolver =
+        new IncrementalResolver(_typeProvider, oldUnitElement, _updateOffset, 0, 0);
+    incrementalResolver._resolveReferences(newComment);
+  }
+
   Token _scan(String code) {
     RecordingErrorListener errorListener = new RecordingErrorListener();
     CharSequenceReader reader = new CharSequenceReader(code);
     Scanner scanner = new Scanner(_unitSource, reader, errorListener);
     Token token = scanner.tokenize();
     _newScanErrors = errorListener.errors;
     return token;
   }
 
+  void _shiftTokens(Token token, int delta) {
+    while (token != null) {
+      if (token.offset > _updateOffset) {
+        token.offset += delta;
+      }
+      _shiftTokens(token.precedingComments, delta);
+      if (token.type == TokenType.EOF) {
+        break;
+      }
+      token = token.next;
+    }
+  }
+
   void _updateEntry() {
     _entry.setValue(DartEntry.SCAN_ERRORS, _newScanErrors);
     _entry.setValue(DartEntry.PARSE_ERRORS, _newParseErrors);
     {
       List<AnalysisError> oldErrors =
           _entry.getValueInLibrary(DartEntry.RESOLUTION_ERRORS, _librarySource);
       List<AnalysisError> errors = _updateErrors(oldErrors, _newResolveErrors);
       _entry.setValueInLibrary(
           DartEntry.RESOLUTION_ERRORS,
           _librarySource,
@@ skipping 48 matching lines @@
       return false;
     }
     return oldToken.lexeme == newToken.lexeme;
   }
 
   static _TokenPair _findFirstDifferentToken(Token oldToken, Token newToken) {
 //    print('first ------------');
     while (oldToken.type != TokenType.EOF && newToken.type != TokenType.EOF) {
 //      print('old: $oldToken @ ${oldToken.offset}');
 //      print('new: $newToken @ ${newToken.offset}');
+      {
+        Token oldComment = oldToken.precedingComments;
+        Token newComment = newToken.precedingComments;
+        if (oldComment != null && newComment != null) {
+          if (!_equalToken(oldComment, newComment, 0)) {
+            return new _TokenPair(oldToken, newToken, true);
+          }
+        }
+      }
       if (!_equalToken(oldToken, newToken, 0)) {
         return new _TokenPair(oldToken, newToken);
       }
       oldToken = oldToken.next;
       newToken = newToken.next;
     }
     return null;
   }
 
   static _TokenPair _findLastDifferentToken(Token oldToken, Token newToken) {
 //    print('last ------------');
     int delta = newToken.offset - oldToken.offset;
     while (oldToken.previous != oldToken && newToken.previous != newToken) {
 //      print('old: $oldToken @ ${oldToken.offset}');
 //      print('new: $newToken @ ${newToken.offset}');
       if (!_equalToken(oldToken, newToken, delta)) {
         return new _TokenPair(oldToken.next, newToken.next);
       }
+      {
+        Token oldComment = oldToken.precedingComments;
+        Token newComment = newToken.precedingComments;
+        if (oldComment != null && newComment != null) {
+          if (!_equalToken(oldComment, newComment, delta)) {
+            return new _TokenPair(oldToken, newToken, true);
+          }
+        }
+      }
       oldToken = oldToken.previous;
       newToken = newToken.previous;
     }
     return null;
   }
 
   static AstNode _findNodeCovering(AstNode root, int offset, int end) {
     NodeLocator nodeLocator = new NodeLocator.con2(offset, end);
     return nodeLocator.searchWithin(root);
   }
 
+  static Token _getBeginTokenNotComment(AstNode node) {
+    Token oldBeginToken = node.beginToken;
+    if (oldBeginToken is CommentToken) {
+      oldBeginToken = (oldBeginToken as CommentToken).parent;
+    }
+    return oldBeginToken;
+  }
+
+
   static List<AstNode> _getParents(AstNode node) {
     List<AstNode> parents = <AstNode>[];
     while (node != null) {
       parents.insert(0, node);
       node = node.parent;
     }
     return parents;
   }
 
-  static void _shiftTokens(Token token, int delta) {
-    while (true) {
-      token.offset += delta;
-      if (token.type == TokenType.EOF) {
-        break;
-      }
-      token = token.next;
+  /**
+   * Set the given [comment] as a "precedingComments" for [parent].
+   */
+  static void _setPrecedingComments(Token parent, CommentToken comment) {
+    if (parent is BeginTokenWithComment) {
+      parent.precedingComments = comment;
+    } else if (parent is KeywordTokenWithComment) {
+      parent.precedingComments = comment;
+    } else if (parent is StringTokenWithComment) {
+      parent.precedingComments = comment;
+    } else if (parent is TokenWithComment) {
+      parent.precedingComments = comment;
+    } else {
+      Type parentType = parent != null ? parent.runtimeType : null;
+      throw new AnalysisException('Uknown parent token type: $parentType');
     }
   }
 }
 
 
 /**
  * The context to resolve an [AstNode] in.
  */
 class ResolutionContext {
   ClassDeclaration enclosingClassDeclaration;
@@ skipping 286 matching lines @@
   @override
   visitSimpleIdentifier(SimpleIdentifier node) {
     _elements[node] = node.staticElement;
   }
 }
 
 
 class _TokenPair {
   final Token oldToken;
   final Token newToken;
-  _TokenPair(this.oldToken, this.newToken);
+  final bool atComment;
+  _TokenPair(this.oldToken, this.newToken, [this.atComment = false]);
 }