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.forEach((qualifiedName, inheritedMethod) {
+      var method = methods[qualifiedName];
+      if (method != null) method.ensureCommentFor(inheritedMethod);
+    });
+  }
+  
   /** 
    * If a class extends a private superclass, find the closest public superclass
    * of the private superclass. 
    */
   String validSuperclass() {
     if (superclass == null) return 'dart.core.Object';
     if (_isVisible(superclass)) return superclass.qualifiedName;
     return superclass.validSuperclass();
   }
   
@@ skipping 29 matching lines @@
     _currentClass = mirror;
     var clazz = _class(mirror);
    
     // Adding inherited parent variables and methods. 
     clazz.parent().forEach((parent) {
       if (_isVisible(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);
   
+  /**
+   * Makes sure that the method with an inherited equivalent have comments.  
+   */
+  void ensureCommentFor(Method inheritedMethod) {
+    if (comment.isNotEmpty) return;
+    entityMap[inheritedMethod.owner].ensureComments();
+    comment = inheritedMethod.comment;
+    commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ? 
+        inheritedMethod.qualifiedName : inheritedMethod.commentInheritedFrom;
+  }
+  
   /// 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) {
+    if (setters.containsKey(qualifiedName)) return setters[qualifiedName];
+    if (getters.containsKey(qualifiedName)) return getters[qualifiedName];
+    if (operators.containsKey(qualifiedName)) return operators[qualifiedName];
+    if (regularMethods.containsKey(qualifiedName)) {
+      return regularMethods[qualifiedName];
+    } 
+    return null;
+  }
+
+  void forEach(void f(String key, Method value)) {
+    setters.forEach(f);
+    getters.forEach(f);
+    operators.forEach(f);
+    regularMethods.forEach(f);
+  }
 }
 
 /**
  * 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()))
   };
 }