Added inherited comments, and where they are inherited from.

pkg/docgen/lib/docgen.dart

 // Copyright (c) 2013, 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.
 
 /**
  * **docgen** is a tool for creating machine readable representations of Dart
  * code metadata, including: classes, members, comments and annotations.
  *
  * docgen is run on a `.dart` file or a directory containing `.dart` files.
  *
@@ skipping 602 matching lines @@
       this.isPrivate = true;
       // Since we are now making the mixin a private class, make all elements 
       // with the mixin as an owner private too. 
       entityMap.values.where((e) => e.owner == qualifiedName)
         .forEach((element) => element.isPrivate = true);
       // Move the subclass up to the next public superclass
       subclasses.forEach((subclass) => addSubclass(entityMap[subclass]));
     }
   }
   
+  /**
+   * 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,
     'qualifiedname': qualifiedName,
     'comment': comment,
     'superclass': superclass == null ? "" : (_filterPrivate(superclass)) ? 
         superclass.qualifiedName : "",
     'implements': new List.from(interfaces.where((e) => _filterPrivate(e))
         .map((e) => e.qualifiedName)),
     'subclass': new List.from(subclasses),
@@ skipping 20 matching lines @@
     _currentClass = mirror;
     var clazz = _class(mirror);
    
     // Adding inherited parent variables and methods. 
     clazz.parent().forEach((parent) {
       if (_filterPrivate(clazz)) {
         parent.addSubclass(clazz);
       }
       clazz.addInherited(parent);
     });
+
+    clazz.ensureComments();
     
     if (isError(mirror.qualifiedName)) {
       errors[mirror.simpleName] = clazz;
     } else if (mirror.isTypedef) {
       if (_includePrivate || !mirror.isPrivate) {
         entityMap[mirror.qualifiedName] = new Typedef(mirror.simpleName, 
             mirror.value.returnType.qualifiedName, _commentToHtml(mirror), 
             _generics(mirror), _parameters(mirror.value.parameters),
             _annotations(mirror), mirror.qualifiedName,  _isPrivate(mirror), 
             mirror.owner.qualifiedName);
@@ skipping 91 matching lines @@
 class Method extends Indexable {
 
   /// Parameters for this method.
   Map<String, Parameter> parameters;
 
   bool isStatic;
   bool isAbstract;
   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;
   
   Method(String name, this.isStatic, this.isAbstract, this.isConst, 
       this.returnType, String comment, this.parameters, this.annotations,
       String qualifiedName, bool isPrivate, String owner) : super(name, comment,
           qualifiedName, isPrivate, owner);
   
   /// Generates a map describing the [Method] object.
   Map toMap() => {
     'name': name,
     'qualifiedname': qualifiedName,
     'comment': comment,
+    'commentfrom': commentInheritedFrom,
     'static': isStatic.toString(),
     'abstract': isAbstract.toString(),
     'constant': isConst.toString(),
     'return': new List.filled(1, returnType.toMap()),
     'parameters': recurseMap(parameters),
     'annotations': new List.from(annotations)
   };
 }
 
 /**
@@ skipping 43 matching lines @@
     }
   }
   
   Map toMap() => {
     'setters': recurseMap(setters),
     'getters': recurseMap(getters),
     'constructors': recurseMap(constructors),
     '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;
+  }
 }
 
 /**
  * A class containing properties of a Dart method/function parameter.
  */
 class Parameter {
 
   String name;
   bool isOptional;
   bool isNamed;
@@ skipping 68 matching lines @@
   String outer;
   List<Type> inner;
   
   Type(this.outer, this.inner);
   
   Map toMap() => {
     'outer': outer,
     'inner': new List.from(inner.map((e) => e.toMap()))
   };
 }