Added inherited comments, and where they are inherited from.

pkg/docgen/lib/docgen.dart

Index: pkg/docgen/lib/docgen.dart
diff --git a/pkg/docgen/lib/docgen.dart b/pkg/docgen/lib/docgen.dart
index 72588c80027d366b598c35327a2fff0f97300f6c..56a64e159d17c9080ca81708d45d2e63f5754eed 100644
--- a/pkg/docgen/lib/docgen.dart
+++ b/pkg/docgen/lib/docgen.dart
@@ -620,6 +620,31 @@ class Class extends Indexable {
     }
   }
   
+  /**
+   * Makes sure that all methods with inherited equivalents have comments.  
+   */
+  void ensureComments() {
+    inheritedMethods.keys.forEach((qualifiedName) {
+      var method = methods[qualifiedName];

[Alan Knight, 2013/08/02 18:32:22]

Since you're actually using the value, this might be more easily written as
   inheritedMethods.forEach((qualifiedName, inheritedMethod) {
...

[janicejl, 2013/08/02 21:40:27]

Done.

+      if (method != null) {
+        if (method.comment == "") {

[Alan Knight, 2013/08/02 18:32:22]

I think this might also work better if you named the inner method and used a
guard clause rather than nesting. e.g.

ensureCommentFor(qualifiedName, inheritedMethod) {
  var method = methods[qualifiedName];
  if (method == null) return;
  

[janicejl, 2013/08/02 21:40:27]

Done.

+          var inheritedMethod = inheritedMethods[qualifiedName];
+          method.comment = inheritedMethod.comment;
+          if (method.comment != "") {

[Alan Knight, 2013/08/02 18:32:22]

In fact, I think this could be rewritten to be much simpler. Is it true that we
never want to overwrite a non-empty comment/commentInheritedFrom? If so, why not
put that logic into the Method class so we can just write
   method.commentInheritedFrom = inheritedMethod.commentInheritedFrom;
And similarly for the comment. If it's not always true, then we could provide a
variant setter that doesn't overwrite.

Then the whole thing can become something like
  Method.ensureCommentFor(inheritedMethod) {
     if (comment.isNotEmpty) return;
     entityMap[inheritedMethod.owner].ensureComments();
     method.comment = inheritedMethod.comment;
     method.commentInheritedFrom = inheritedMethod.commentInheritedFrom;
 }

That might be slightly inefficient, as I think it will check the whole of the
superclass for each method that doesn't have a comment in the subclass, but
there's probably a way to find just the inherited method and ensureComments on
it individually.

[janicejl, 2013/08/02 21:40:27]

Done.

+            method.commentInheritedFrom = 
+                inheritedMethod.commentInheritedFrom == "" ? 
+                    inheritedMethod.qualifiedName : 
+                      inheritedMethod.commentInheritedFrom;
+          } else {
+            entityMap[inheritedMethod.owner].ensureComments();
+            method.comment = inheritedMethod.comment;
+            method.commentInheritedFrom = inheritedMethod.commentInheritedFrom;
+          }
+        }
+      }
+    });
+  }
+  
   /// Generates a map describing the [Class] object.
   Map toMap() => {
     'name': name,
@@ -660,6 +685,8 @@ class ClassGroup {
       }
       clazz.addInherited(parent);
     });
+
+    clazz.ensureComments();
     
     if (isError(mirror.qualifiedName)) {
       errors[mirror.simpleName] = clazz;
@@ -771,6 +798,9 @@ class Method extends Indexable {
   bool isConst;
   Type returnType;
   
+  /// Qualified name to state where the comment is inherited from. 
+  String commentInheritedFrom = "";
+  
   /// List of the meta annotations on the method.
   List<String> annotations;
   
@@ -784,6 +814,7 @@ class Method extends Indexable {
     'name': name,
     'qualifiedname': qualifiedName,
     'comment': comment,
+    'commentfrom': commentInheritedFrom,
     'static': isStatic.toString(),
     'abstract': isAbstract.toString(),
     'constant': isConst.toString(),
@@ -847,6 +878,33 @@ class MethodGroup {
     'operators': recurseMap(operators),
     'methods': recurseMap(regularMethods)
   };
+
+  Method operator [](String qualifiedName) {
+    var method = setters[qualifiedName];

[Alan Knight, 2013/08/02 18:32:22]

I don't love the deep nesting. Redo as a loop over [setters, getters, ...]?

[janicejl, 2013/08/02 21:40:27]

Done.

+    if (method != null) return method;
+    else {
+      method = getters[qualifiedName];
+      if (method != null) return method;
+      else {
+        method = operators[qualifiedName];
+        if (method != null) return method;
+        else {
+          method = regularMethods[qualifiedName];
+          if (method != null) return method;
+          else return null;
+        }
+      }
+    }
+  }
+
+  Iterable<String> get keys {

[Alan Knight, 2013/08/02 18:32:22]

=> [setters, getters, operators, regularMethods].expand((x) => x.keys);

with optional toList() on the end.

[janicejl, 2013/08/02 21:40:27]

Done.

+    var qualifiedNames = [];
+    qualifiedNames.addAll(setters.keys);
+    qualifiedNames.addAll(getters.keys);
+    qualifiedNames.addAll(operators.keys);
+    qualifiedNames.addAll(regularMethods.keys);
+    return qualifiedNames;
+  }
 }
 
 /**