Added code to associate a dart doc comment with a dart declaration node.

compiler/java/com/google/dart/compiler/parser/CommentPreservingParser.java

Index: compiler/java/com/google/dart/compiler/parser/CommentPreservingParser.java
===================================================================
--- compiler/java/com/google/dart/compiler/parser/CommentPreservingParser.java	(revision 2064)
+++ compiler/java/com/google/dart/compiler/parser/CommentPreservingParser.java	(working copy)
@@ -8,11 +8,16 @@
 import com.google.dart.compiler.DartSource;
 import com.google.dart.compiler.Source;
 import com.google.dart.compiler.ast.DartComment;
+import com.google.dart.compiler.ast.DartDeclaration;
+import com.google.dart.compiler.ast.DartNode;
+import com.google.dart.compiler.ast.DartNodeTraverser;
 import com.google.dart.compiler.ast.DartUnit;
 import com.google.dart.compiler.metrics.CompilerMetrics;
 import com.google.dart.compiler.util.DartSourceString;
 
 import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
 import java.util.List;
 
 /**
@@ -121,17 +126,106 @@
   @Override
   public DartUnit parseUnit(DartSource input) {
     DartUnit unit = super.parseUnit(input);
+
     String sourceString = context.source;
     Source source = new DartSourceString(null, sourceString);
+
     for (int[] loc : context.getCommentLocs()) {
       DartComment.Style style = getCommentStyle(sourceString, loc[0]);
       if (!onlyDartDoc || style == DartComment.Style.DART_DOC) {
         unit.addComment(new DartComment(source, loc[0], loc[1] - loc[0], loc[2], loc[3], style));
       }
     }
+
+    List<DartComment> comments = unit.getComments();
+
+    if (comments != null) {
+      assignDartComments(unit, comments);
+    }
+
     return unit;
   }
 
+  private void assignDartComments(DartUnit unit, List<DartComment> comments) {
+    // Collect the AST nodes in a list.
+    final List<DartNode> astNodes = new ArrayList<DartNode>();
+    unit.accept(new DartNodeTraverser<DartNode>() {
+      @Override
+      public DartNode visitNode(DartNode node) {

[Brian Wilkerson, 2011/12/05 16:14:24]

We could improve the performance by overriding visitDeclaration(DartDeclaration)
rather than visitNode(DartNode).

[devoncarew, 2011/12/05 19:30:39]

Done.

+        astNodes.add(node);
+        return super.visitNode(node);
+      }
+    });
+
+    // Collect all the nodes in one list.
+    List<DartNode> nodes = new ArrayList<DartNode>();
+
+    nodes.addAll(comments);
+    nodes.addAll(astNodes);
+
+    // Sort the nodes by their position in the source file.
+    Collections.sort(nodes, new Comparator<DartNode>() {
+      @Override
+      public int compare(DartNode node1, DartNode node2) {
+        return node1.getSourceStart() - node2.getSourceStart();
+      }
+    });
+
+    // Assign dart docs to their associated DartDeclarations.
+    for (int i = 0; i < nodes.size(); i++) {
+      DartNode node = nodes.get(i);
+
+      if (node instanceof DartComment) {
+        DartComment comment = (DartComment)node;
+
+        if (comment.isDartDoc() && (i + 1 < nodes.size())) {
+          DartNode next = nodes.get(i + 1);
+
+          if (next instanceof DartDeclaration) {
+            DartDeclaration<?> decl = (DartDeclaration<?>)next;
+
+            if (!commentContainedBySibling(comment, decl)) {
+              decl.setDartDoc(comment);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  private boolean commentContainedBySibling(DartComment comment, DartDeclaration<?> node) {
+    for (DartNode child : getChildren(node.getParent())) {
+      if (child != node && !(child instanceof DartComment)) {
+        if (isContainedBy(comment, child)) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  private List<DartNode> getChildren(DartNode parent) {

[mmendez, 2011/12/05 17:58:50]

Nit: You are probably redoing a lot of work here when dealing with methods
declared on a class or when there are a lot of top level classes.  Perhaps a
range sort might be better.

[devoncarew, 2011/12/05 19:30:39]

Good catch - it looks like we are unnecessarily re-doing calculations. From
thinking about it, I think I prefer the simplicity of this method to the added
complexity of caching the child information for the nodes. It's fairly
light-weight to re-calculate. Unless I hear objections, I'll submit this CL as
is -

+    final List<DartNode> children = new ArrayList<DartNode>();
+
+    parent.visitChildren(new DartNodeTraverser<DartNode>() {
+      @Override
+      public DartNode visitNode(DartNode node) {
+        children.add(node);
+        return null;
+      }
+    });
+
+    return children;
+  }
+
+  private boolean isContainedBy(DartNode node, DartNode containedByNode) {
+    int nodeEnd = node.getSourceStart() + node.getSourceLength();
+    int containedByEnd = containedByNode.getSourceStart() + containedByNode.getSourceLength();
+
+    return node.getSourceStart() >= containedByNode.getSourceStart() && nodeEnd <= containedByEnd; 
+  }
+
   /**
    * Return the style of the comment in the given string.
    *