Members and comments inherited in dartdoc.

pkg/dartdoc/lib/dartdoc.dart

 // Copyright (c) 2012, 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.
 
 /**
  * To generate docs for a library, run this script with the path to an
  * entrypoint .dart file, like:
  *
  *     $ dart dartdoc.dart foo.dart
  *
@@ skipping 705 matching lines @@
     _currentType = null;
 
     startFile(libraryUrl(library));
     writeHeader('${library.simpleName} Library',
         [library.simpleName, libraryUrl(library)]);
     writeln('<h2><strong>${library.simpleName}</strong> library</h2>');
 
     // Look for a comment for the entire library.
     final comment = getLibraryComment(library);
     if (comment != null) {
-      writeln('<div class="doc">$comment</div>');
+      writeln('<div class="doc">${comment.html}</div>');
     }
 
     // Document the top-level members.
     docMembers(library);
 
     // Document the types.
     final classes = <InterfaceMirror>[];
     final interfaces = <InterfaceMirror>[];
     final typedefs = <TypedefMirror>[];
     final exceptions = <InterfaceMirror>[];
@@ skipping 25 matching lines @@
     for (final type in library.types.getValues()) {
       if (type.isPrivate) continue;
 
       docType(type);
     }
   }
 
   void docTypes(List types, String header) {
     if (types.length == 0) return;
 
+    writeln('<div>');
     writeln('<h3>$header</h3>');
 
     for (final type in types) {
       writeln(
           '''
           <div class="type">
           <h4>
             ${a(typeUrl(type), "<strong>${typeName(type)}</strong>")}
           </h4>
           </div>
           ''');
     }
+    writeln('</div>');
   }
 
   void docType(InterfaceMirror type) {
     if (verbose) {
       print('- ${type.simpleName}');
     }
     _totalTypes++;
     _currentType = type;
 
     startFile(typeUrl(type));
@@ skipping 13 matching lines @@
       '${typeName(type)} ${kind}';
     writeHeader('$typeTitle / ${type.library.simpleName} Library',
         [type.library.simpleName, libraryUrl(type.library),
          typeName(type), typeUrl(type)]);
     writeln(
         '''
         <h2><strong>${typeName(type, showBounds: true)}</strong>
           $kind
         </h2>
         ''');
+    writeln('<button id="show-inherited" class="show-inherited">'
+            'Hide inherited</button>');
 
-    docCode(type.location, getTypeComment(type));
+    docCode(type, type.location, getTypeComment(type));
     docInheritance(type);
     docTypedef(type);
+
     docConstructors(type);
     docMembers(type);
 
     writeTypeFooter();
     writeFooter();
     endFile();
   }
 
   /** Override this to write additional content at the end of a type's page. */
   void writeTypeFooter() {
@@ skipping 111 matching lines @@
   /**
    * Documents the definition of [type] if it is a typedef.
    */
   void docTypedef(TypeMirror type) {
     if (type is! TypedefMirror) {
       return;
     }
     writeln('<div class="method"><h4 id="${type.simpleName}">');
 
     if (includeSource) {
-      writeln('<span class="show-code">Code</span>');
+      writeln('<button class="show-code">Code</button>');
     }
 
     write('typedef ');
     annotateType(type, type.definition, type.simpleName);
 
     write(''' <a class="anchor-link" href="#${type.simpleName}"
               title="Permalink to ${type.simpleName}">#</a>''');
     writeln('</h4>');
 
-    docCode(type.location, null, showCode: true);
+    docCode(type, type.location, null, showCode: true);
 
     writeln('</div>');
   }
 
   /** Document the constructors for [Type], if any. */
   void docConstructors(InterfaceMirror type) {
     final constructors = <MethodMirror>[];
     for (var constructor in type.constructors.getValues()) {
        if (!constructor.isPrivate) {
          constructors.add(constructor);
        }
     }
 
     if (constructors.length > 0) {
+      writeln('<div>');
       writeln('<h3>Constructors</h3>');
       constructors.sort((x, y) => x.constructorName.toUpperCase().compareTo(
                                   y.constructorName.toUpperCase()));
 
       for (final constructor in constructors) {
         docMethod(type, constructor);
       }
+      writeln('</div>');
     }
   }
 
   void docMembers(ObjectMirror host) {
     // Collect the different kinds of members.
     final staticMethods = [];
     final staticFields = [];
+    final memberMap = new Map<String,MemberMirror>();
     final instanceMethods = [];
     final instanceFields = [];
 
-    for (MemberMirror member in orderByName(host.declaredMembers.getValues())) {
-      if (member.isPrivate) continue;
+    host.declaredMembers.forEach((_, MemberMirror member) {
+      if (member.isPrivate) return;
+      if (member.isStatic) {
+        if (member.isMethod) {
+          staticMethods.add(member);
+        } else  if (member.isField) {
+          staticFields.add(member);
+        }
+      }
+    });
 
-      final methods = member.isStatic ? staticMethods : instanceMethods;
-      final fields = member.isStatic ? staticFields : instanceFields;
+    if (host is InterfaceMirror) {
+      var iterable = new HierarchyIterable(host, includeType: true);
+      for (InterfaceMirror type in iterable) {
+        type.declaredMembers.forEach((_, MemberMirror member) {
+          if (member.isPrivate) return;
+          if (!member.isStatic) {
+            memberMap.putIfAbsent(member.simpleName, () => member);
+          }
+        });
+      }
+    }
 
+    memberMap.forEach((_, MemberMirror member) {
       if (member.isMethod) {
-        methods.add(member);
-      } else if (member.isField) {
-        fields.add(member);
+        instanceMethods.add(member);
+      } else  if (member.isField) {
+        instanceFields.add(member);
       }
+    });
+
+    if (staticFields.length > 0) {
+      final title = host is LibraryMirror ? 'Variables' : 'Static Fields';
+      writeln('<div>');
+      writeln('<h3>$title</h3>');
+      for (final field in orderByName(staticFields)) {
+        docField(host, field);
+      }
+      writeln('</div>');
     }
 
     if (staticMethods.length > 0) {
       final title = host is LibraryMirror ? 'Functions' : 'Static Methods';
+      writeln('<div>');
       writeln('<h3>$title</h3>');
       for (final method in orderByName(staticMethods)) {
         docMethod(host, method);
       }
+      writeln('</div>');
     }
 
-    if (staticFields.length > 0) {
-      final title = host is LibraryMirror ? 'Variables' : 'Static Fields';
-      writeln('<h3>$title</h3>');
-      for (final field in orderByName(staticFields)) {
+    if (instanceFields.length > 0) {
+      writeln('<div>');
+      writeln('<h3>Fields</h3>');
+      for (final field in orderByName(instanceFields)) {
         docField(host, field);
       }
+      writeln('</div>');
     }
 
     if (instanceMethods.length > 0) {
+      writeln('<div>');
       writeln('<h3>Methods</h3>');
       for (final method in orderByName(instanceMethods)) {
         docMethod(host, method);
       }
-    }
-
-    if (instanceFields.length > 0) {
-      writeln('<h3>Fields</h3>');
-      for (final field in orderByName(instanceFields)) {
-        docField(host, field);
-      }
+      writeln('</div>');
     }
   }
 
   /**
    * Documents the [method] in type [type]. Handles all kinds of methods
    * including getters, setters, and constructors.
    */
   void docMethod(ObjectMirror host, MethodMirror method) {
     _totalMembers++;
     _currentMember = method;
 
     bool showCode = includeSource && !method.isAbstract;
+    bool inherited = host != method.surroundingDeclaration;
 
-    writeln('<div class="method"><h4 id="${memberAnchor(method)}">');
+    writeln('<div class="method${inherited ? ' inherited': ''}">'
+            '<h4 id="${memberAnchor(method)}">');
 
     if (showCode) {
-      writeln('<span class="show-code">Code</span>');
+      writeln('<button class="show-code">Code</button>');
     }
 
     if (method.isConstructor) {
       if (method.isFactory) {
         write('factory ');
       } else {
         write(method.isConst ? 'const ' : 'new ');
       }
     } else if (method.isAbstract) {
       write('abstract ');
@@ skipping 15 matching lines @@
 
     write('<strong>$name</strong>');
 
     docParamList(host, method.parameters);
 
     var prefix = host is LibraryMirror ? '' : '${typeName(host)}.';
     write(''' <a class="anchor-link" href="#${memberAnchor(method)}"
               title="Permalink to $prefix$name">#</a>''');
     writeln('</h4>');
 
-    docCode(method.location, getMethodComment(method), showCode: showCode);
+    if (inherited) {
+      write('<div class="inherited-from">inherited from ');
+      annotateType(host, method.surroundingDeclaration);
+      write('</div>');
+    }
+
+    docCode(host, method.location, getMemberComment(method), showCode: showCode);
 
     writeln('</div>');
   }
 
   /** Documents the field [field] of type [type]. */
   void docField(ObjectMirror host, FieldMirror field) {
     _totalMembers++;
     _currentMember = field;
 
-    writeln('<div class="field"><h4 id="${memberAnchor(field)}">');
+    bool inherited = host != field.surroundingDeclaration;
+
+    writeln('<div class="field${inherited ? ' inherited' : ''}">'
+            '<h4 id="${memberAnchor(field)}">');
 
     if (includeSource) {
-      writeln('<span class="show-code">Code</span>');
+      writeln('<button class="show-code">Code</button>');
     }
 
     if (field.isFinal) {
       write('final ');
     } else if (field.type.isDynamic) {
       write('var ');
     }
 
     annotateType(host, field.type);
     var prefix = host is LibraryMirror ? '' : '${typeName(host)}.';
     write(
         '''
         <strong>${field.simpleName}</strong> <a class="anchor-link"
             href="#${memberAnchor(field)}"
             title="Permalink to $prefix${field.simpleName}">#</a>
         </h4>
         ''');
 
-    docCode(field.location, getFieldComment(field), showCode: true);
+    if (inherited) {
+      write('<div class="inherited-from">inherited from ');
+      annotateType(host, field.surroundingDeclaration);
+      write('</div>');
+    }
+
+    docCode(host, field.location, getMemberComment(field), showCode: true);
+
     writeln('</div>');
   }
 
   void docParamList(ObjectMirror enclosingType,
                     List<ParameterMirror> parameters) {
     write('(');
     bool first = true;
     bool inOptionals = false;
     for (final parameter in parameters) {
       if (!first) write(', ');
@@ skipping 15 matching lines @@
     }
 
     if (inOptionals) write(']');
     write(')');
   }
 
   /**
    * Documents the code contained within [span] with [comment]. If [showCode]
    * is `true` (and [includeSource] is set), also includes the source code.
    */
-  void docCode(Location location, String comment, [bool showCode = false]) {
+  void docCode(ObjectMirror host, Location location, DocComment comment,
+               [bool showCode = false]) {
     writeln('<div class="doc">');
     if (comment != null) {
-      writeln(comment);
+      if (comment.inheritedFrom !== null) {
+        writeln('<div class="inherited">');
+        writeln(comment.html);
+        write('<div class="docs-inherited-from">docs inherited from ');
+        annotateType(host, comment.inheritedFrom);
+        write('</div>');
+        writeln('</div>');
+      } else {
+        writeln(comment.html);
+      }
     }
 
     if (includeSource && showCode) {
       writeln('<pre class="source">');
       writeln(md.escapeHtml(unindentCode(location)));
       writeln('</pre>');
     }
 
     writeln('</div>');
   }
 
+  DocComment createDocComment(String text, [InterfaceMirror inheritedFrom]) =>
+      new DocComment(text, inheritedFrom);
+
 
   /** Get the doc comment associated with the given library. */
-  String getLibraryComment(LibraryMirror library) {
+  DocComment getLibraryComment(LibraryMirror library) {
     // Look for a comment for the entire library.
     final comment = _comments.findLibrary(library.location.source);
-    if (comment != null) {
-      return md.markdownToHtml(comment);
-    }
-    return null;
+    if (comment == null) return null;
+    return createDocComment(comment);
   }
 
   /** Get the doc comment associated with the given type. */
-  String getTypeComment(TypeMirror type) {
+  DocComment getTypeComment(TypeMirror type) {
     String comment = _comments.find(type.location);
     if (comment == null) return null;
-    return commentToHtml(comment);
+    return createDocComment(comment);
   }
 
-  /** Get the doc comment associated with the given method. */
-  String getMethodComment(MethodMirror method) {
-    String comment = _comments.find(method.location);
+  /**
+   * Get the doc comment associated with the given member.
+   *
+   * If no comment was found on the member, the hierarchy is traversed to find
+   * an inherited comment, favouring comments inherited from classes over
+   * comments inherited from interfaces.
+   */
+  DocComment getMemberComment(MemberMirror member) {
+    String comment = _comments.find(member.location);
+    InterfaceMirror inheritedFrom = null;
+    if (comment == null) {
+      if (member.surroundingDeclaration is InterfaceMirror) {
+        var iterable =
+            new HierarchyIterable(member.surroundingDeclaration,
+                                  includeType: false);
+        for (InterfaceMirror type in iterable) {
+          var inheritedMember = type.declaredMembers[member.simpleName];
+          if (inheritedMember is MemberMirror) {
+            comment = _comments.find(inheritedMember.location);
+            if (comment != null) {
+              inheritedFrom = type;
+              break;
+            }
+          }
+        }
+      }
+    }
     if (comment == null) return null;
-    return commentToHtml(comment);
+    return createDocComment(comment, inheritedFrom);
   }
 
-  /** Get the doc comment associated with the given field. */
-  String getFieldComment(FieldMirror field) {
-    String comment = _comments.find(field.location);
-    if (comment == null) return null;
-    return commentToHtml(comment);
-  }
-
-  String commentToHtml(String comment) => md.markdownToHtml(comment);
-
   /**
    * Converts [fullPath] which is understood to be a full path from the root of
    * the generated docs to one relative to the current file.
    */
   String relativePath(String fullPath) {
     // Don't make it relative if it's an absolute path.
     if (isAbsolute(fullPath)) return fullPath;
 
     // TODO(rnystrom): Walks all the way up to root each time. Shouldn't do
     // this if the paths overlap.
@@ skipping 240 matching lines @@
     if (currentLibrary != null) {
       // See if it's a constructor
       final constructorLink = (() {
         final match =
             new RegExp(r'new ([\w$]+)(?:\.([\w$]+))?').firstMatch(name);
         if (match == null) return;
         String typeName = match[1];
         InterfaceMirror foundtype = currentLibrary.types[typeName];
         if (foundtype == null) return;
         String constructorName =
-            match[2] == null ? typeName : '$typeName.${match[2]}';
+            (match[2] == null) ? typeName : '$typeName.${match[2]}';
         final constructor =
             foundtype.constructors[constructorName];
         if (constructor == null) return;
         return makeLink(memberUrl(constructor));
       })();
       if (constructorLink != null) return constructorLink;
 
       // See if it's a member of another type
       final foreignMemberLink = (() {
         final match = new RegExp(r'([\w$]+)\.([\w$]+)').firstMatch(name);
@@ skipping 69 matching lines @@
 
 /**
  * Used to report an unexpected error in the DartDoc tool or the
  * underlying data
  */
 class InternalError {
   final String message;
   const InternalError(this.message);
   String toString() => "InternalError: '$message'";
 }
+
+class DocComment {
+  final String text;
+
+  /**
+   * Non-null if the comment is inherited from another declaration.
+   */
+  final InterfaceMirror inheritedFrom;
+
+  DocComment(this.text, [this.inheritedFrom = null]) {
+    assert(text != null && !text.trim().isEmpty());
+  }
+
+  String get html => md.markdownToHtml(text);
+
+  String toString() => text;
+}