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 557 matching lines @@
     final List members = docMembersJson(library.declaredMembers);
     if (!members.isEmpty()) {
       libraryInfo[MEMBERS] = members;
     }
 
     final types = [];
     for (InterfaceMirror type in orderByName(library.types.getValues())) {
       if (type.isPrivate) continue;
 
       var typeInfo = {};
-      typeInfo[NAME] = type.simpleName;
+      typeInfo[NAME] = type.displayName;
       if (type.isClass) {
         typeInfo[KIND] = CLASS;
       } else if (type.isInterface) {
         typeInfo[KIND] = INTERFACE;
       } else {
         assert(type.isTypedef);
         typeInfo[KIND] = TYPEDEF;
       }
       final List typeMembers = docMembersJson(type.declaredMembers);
       if (!typeMembers.isEmpty()) {
         typeInfo[MEMBERS] = typeMembers;
       }
 
       if (!type.declaration.typeVariables.isEmpty()) {
         final typeVariables = [];
         for (final typeVariable in type.declaration.typeVariables) {
-          typeVariables.add(typeVariable.simpleName);
+          typeVariables.add(typeVariable.displayName);
         }
         typeInfo[ARGS] = Strings.join(typeVariables, ', ');
       }
       types.add(typeInfo);
     }
     if (!types.isEmpty()) {
       libraryInfo[TYPES] = types;
     }
 
     libraryList.add(libraryInfo);
   }
 
   List docMembersJson(Map<Object,MemberMirror> memberMap) {
     final members = [];
     for (MemberMirror member in orderByName(memberMap.getValues())) {
       if (member.isPrivate) continue;
 
       var memberInfo = {};
       if (member.isField) {
-        memberInfo[NAME] = member.simpleName;
         memberInfo[KIND] = FIELD;
       } else {
         MethodMirror method = member;
         if (method.isConstructor) {
-          if (method.constructorName != '') {
-            memberInfo[NAME] = '${method.simpleName}.${method.constructorName}';
-            memberInfo[KIND] = CONSTRUCTOR;
-          } else {
-            memberInfo[NAME] = member.simpleName;
-            memberInfo[KIND] = CONSTRUCTOR;
-          }
-        } else if (method.isOperator) {
-          memberInfo[NAME] = '${method.simpleName} ${method.operatorName}';
-          memberInfo[KIND] = METHOD;
+          memberInfo[KIND] = CONSTRUCTOR;
         } else if (method.isSetter) {
-          memberInfo[NAME] = member.simpleName;
           memberInfo[KIND] = SETTER;
         } else if (method.isGetter) {
-          memberInfo[NAME] = member.simpleName;
           memberInfo[KIND] = GETTER;
         } else {
-          memberInfo[NAME] = member.simpleName;
           memberInfo[KIND] = METHOD;
         }
       }
+      memberInfo[NAME] = member.displayName;
       var anchor = memberAnchor(member);
       if (anchor != memberInfo[NAME]) {
         memberInfo[LINK_NAME] = anchor;
       }
       members.add(memberInfo);
     }
     return members;
   }
 
   void docNavigation() {
@@ skipping 74 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('<span class="show-inherited">Hide inherited</span>');

[Lasse Reichstein Nielsen, 2012/10/04 07:41:19]

Use a button! This is clearly a clickable thing with a non-navigating behavior,
so it should be a button. 
Also, give it an id instead of a class. It should be unique in the document.

[Johnni Winther, 2012/10/04 12:46:21]

Done.

 
-    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 74 matching lines @@
           typeSpan(supertypes[i]);
           write(' > ');
         }
 
         // Write this class.
         typeSpan(type);
         writeln('</p>');
       }
 
       listTypes(subtypes, 'Subclasses');
-      listTypes(type.interfaces.getValues(), 'Implements');
+      listTypes(type.interfaces, 'Implements');
     } else {
       // Show the default class.
       if (type.defaultType != null) {
         listTypes([type.defaultType], 'Default class');
       }
 
       // List extended interfaces.
-      listTypes(type.interfaces.getValues(), 'Extends');
+      listTypes(type.interfaces, 'Extends');
 
       // List subinterfaces and implementing classes.
       final subinterfaces = [];
       final implementing = [];
 
       for (final subtype in subtypes) {
         if (subtype.isClass) {
           implementing.add(subtype);
         } else {
           subinterfaces.add(subtype);
@@ skipping 18 matching lines @@
       writeln('<span class="show-code">Code</span>');
     }
 
     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.simpleName.toUpperCase().compareTo(
                                   y.simpleName.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) {

[Lasse Reichstein Nielsen, 2012/10/04 07:41:19]

Add a host.forEachDeclaredMember method instead of acting directly on the map.
When you even ignore the key, it's obvious that the Map is an internal storage
representation that needn't be externally visible.

[Johnni Winther, 2012/10/04 12:46:21]

[declaredMembers] is also used for lookup where the key is used. This is
actually the specific case because we want to go through all members.

+      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>');

[Lasse Reichstein Nielsen, 2012/10/04 07:41:19]

Why wrap it in a div if it doesn't even have a class?
Seems like pure overhead.

[Johnni Winther, 2012/10/04 12:46:21]

Not quite sure. It was requested in dartbug.com/1156 and has something to do
with user search.

       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>');
     }
 
     if (method.isConstructor) {
       if (method.isFactory) {
         write('factory ');
       } else {
         write(method.isConst ? 'const ' : 'new ');
       }
     } else if (method.isAbstract) {
       write('abstract ');
     }
 
-    if (method.constructorName == null) {
+    if (!method.isConstructor) {
       annotateType(host, method.returnType);
     }
 
-    var name = method.simpleName;
+    var name = method.displayName;
     // Translate specially-named methods: getters, setters, operators.
     if (method.isGetter) {
       // Getter.
       name = 'get $name';
     } else if (method.isSetter) {
       // Setter.
       name = 'set $name';
-    } else if (method.isOperator) {
-      name = 'operator ${method.operatorName}';
     }
 
     write('<strong>$name</strong>');
 
-    // Named constructors.
-    if (method.constructorName != null && method.constructorName != '') {
-      write('.');
-      write(method.constructorName);
-    }
-
     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>');
     }
 
     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 28 matching lines @@
   }
 
   /** Gets the URL for the documentation for [member]. */
   String memberUrl(MemberMirror member) {
     String url = typeUrl(member.surroundingDeclaration);
     return '$url#${memberAnchor(member)}';
   }
 
   /** Gets the anchor id for the document for [member]. */
   String memberAnchor(MemberMirror member) {
-    if (member.isField) {
-      return member.simpleName;
-    }
-    MethodMirror method = member;
-    if (method.isConstructor) {
-      if (method.constructorName == '') {
-        return method.simpleName;
-      } else {
-        return '${method.simpleName}.${method.constructorName}';
-      }
-    } else if (method.isOperator) {
-      return '${method.simpleName} ${method.operatorName}';
-    } else if (method.isSetter) {
-      return '${method.simpleName}=';
-    } else {
-      return method.simpleName;
-    }
+    return member.simpleName;
   }
 
   /**
    * Creates a hyperlink. Handles turning the [href] into an appropriate
    * relative path from the current file.
    */
   String a(String href, String contents, [String css]) {
     // Mark outgoing external links, mainly so we can style them.
     final rel = isAbsolute(href) ? ' ref="external"' : '';
     final cssClass = css == null ? '' : ' class="$css"';
@@ skipping 173 matching lines @@
         if (parameter.simpleName == name) {
           final element = new md.Element.text('span', name);
           element.attributes['class'] = 'param';
           return element;
         }
       }
     }
 
     // See if it's another member of the current type.
     if (currentType != null) {
-      final foundMember = findMirror(currentType.declaredMembers, name);
+      final foundMember = currentType.declaredMembers[name];
       if (foundMember != null) {
         return makeLink(memberUrl(foundMember));
       }
     }
 
     // See if it's another type or a member of another type in the current
     // library.
     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;
-        InterfaceMirror foundtype = findMirror(currentLibrary.types, match[1]);
+        String typeName = match[1];
+        InterfaceMirror foundtype = currentLibrary.types[typeName];
         if (foundtype == null) return;
+        String constructorName =
+            match[2] == null ? typeName : '$typeName.${match[2]}';

[Lasse Reichstein Nielsen, 2012/10/04 07:41:19]

I recommend parentheses around any non-trivial condition in a condition
expression.

[Johnni Winther, 2012/10/04 12:46:21]

Done.

         final constructor =
-            findMirror(foundtype.constructors,
-                            match[2] == null ? '' : match[2]);
+            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);
         if (match == null) return;
-        InterfaceMirror foundtype = findMirror(currentLibrary.types, match[1]);
+        InterfaceMirror foundtype = currentLibrary.types[match[1]];
         if (foundtype == null) return;
-        MemberMirror foundMember = findMirror(foundtype.declaredMembers, match[2]);
+        MemberMirror foundMember = foundtype.declaredMembers[match[2]];
         if (foundMember == null) return;
         return makeLink(memberUrl(foundMember));
       })();
       if (foreignMemberLink != null) return foreignMemberLink;
 
-      InterfaceMirror foundType = findMirror(currentLibrary.types, name);
+      InterfaceMirror foundType = currentLibrary.types[name];
       if (foundType != null) {
         return makeLink(typeUrl(foundType));
       }
 
       // See if it's a top-level member in the current library.
-      MemberMirror foundMember = findMirror(currentLibrary.declaredMembers, name);
+      MemberMirror foundMember = currentLibrary.declaredMembers[name];
       if (foundMember != null) {
         return makeLink(memberUrl(foundMember));
       }
     }
 
     // TODO(rnystrom): Should also consider:
     // * Names imported by libraries this library imports.
     // * Type parameters of the enclosing type.
 
     return new md.Element.text('code', name);
@@ skipping 43 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);

[Lasse Reichstein Nielsen, 2012/10/04 07:41:19]

Why isn't the "inherited from" HTML added by this class, instead of doing it in
several places above?

If there are different versions of the comment, you could have different getters
for the different cases, but localized in the DocComment class.

[Johnni Winther, 2012/10/04 12:46:21]

The functionality might fit in the DocComment class if it had more information.
We want better diagnostics in parsing markdown, so it might all be put here in a
later CL.

+
+  String toString() => text;
+}