fix completion target handling of comments

pkg/analysis_server/lib/src/services/completion/completion_target.dart

 import 'package:analyzer/src/generated/ast.dart';
 import 'package:analyzer/src/generated/element.dart';
 import 'package:analyzer/src/generated/scanner.dart';
 import 'package:analyzer/src/generated/utilities_dart.dart';
 
 int _computeArgIndex(AstNode containingNode, Object entity) {
   var argList = containingNode;
   if (argList is ArgumentList) {
     NodeList<Expression> args = argList.arguments;
     for (int index = 0; index < args.length; ++index) {
@@ skipping 138 matching lines @@
         } else if (entity is AstNode) {
           // If the last token in the node isn't a candidate target, then
           // neither the node nor any of its descendants can possibly be the
           // completion target, so we can skip the node entirely.
           if (!_isCandidateToken(entity.endToken, offset)) {
             continue;
           }
 
           // If the node is a candidate target, then we are done.
           if (_isCandidateNode(entity, offset)) {
+            // Check to see if the offset is in a preceeding comment
+            Token commentToken = _getContainingCommentToken(entity, offset);
+            if (commentToken != null) {
+              entity = commentToken;
+              // If the preceeding comment is dartdoc token then update
+              // the containing node to be the dartdoc comment
+              Comment docComment =
+                  _getContainingDocComment(containingNode, commentToken);
+              if (docComment != null) {
+                containingNode = docComment;
+              }
+            }
             return new CompletionTarget._(containingNode, entity);
           }
 
           // Otherwise, the completion target is somewhere inside the entity,
           // so we need to jump to the start of the outer loop to examine its
           // contents.
           containingNode = entity;
           continue outerLoop;
         } else {
           // Unexpected entity found (all entities in a parse tree should be
@@ skipping 58 matching lines @@
           return _isFunctionalParameter(methodElem.parameters, argIndex);
         } else if (methodElem is FunctionElement) {
           return _isFunctionalParameter(methodElem.parameters, argIndex);
         }
       }
     }
     return false;
   }
 
   /**
+   * Determine if the offset is contained in a preceeding comment token
+   * and return that token, otherwise return `null`.
+   */
+  static Token _getContainingCommentToken(AstNode node, int offset) {
+    if (offset >= node.offset) {
+      return null;
+    }
+    Token token = node.beginToken;
+    if (token == null) {
+      return null;
+    }
+    token = token.precedingComments;
+    while (token != null) {
+      if (offset <= token.offset) {
+        return null;
+      }
+      if (offset <= token.end) {
+        if (token.type == TokenType.SINGLE_LINE_COMMENT || offset < token.end) {
+          return token;
+        }
+      }
+      token = token.next;
+    }
+    return null;
+  }
+
+  /**
+   * Determine if the given token is part of the given node's dart doc.
+   */
+  static Comment _getContainingDocComment(AstNode node, Token token) {
+    if (node is AnnotatedNode) {
+      Comment docComment = node.documentationComment;
+      if (docComment != null && docComment.tokens.contains(token)) {
+        return docComment;
+      }
+    }
+    return null;
+  }
+
+  /**
    * Determine whether [node] could possibly be the [entity] for a
    * [CompletionTarget] associated with the given [offset].
    */
   static bool _isCandidateNode(AstNode node, int offset) {
     // If the node's first token is a keyword or identifier, then the node is a
     // candidate entity if its first token is.
     Token beginToken = node.beginToken;
     if (beginToken.type == TokenType.KEYWORD ||
         beginToken.type == TokenType.IDENTIFIER) {
       return _isCandidateToken(beginToken, offset);
@@ skipping 37 matching lines @@
       if (param.parameterKind == ParameterKind.NAMED) {
         // TODO(danrubel) handle named parameters
         return false;
       } else {
         return paramType is FunctionType || paramType is FunctionTypeAlias;
       }
     }
     return false;
   }
 }