Members and comments inherited in dartdoc.

utils/apidoc/apidoc.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.
 
 /**
  * This generates the reference documentation for the core libraries that come
  * with dart. It is built on top of dartdoc, which is a general-purpose library
  * for generating docs from any Dart code. This library extends that to include
  * additional information and styling specific to our standard library.
  *
@@ skipping 136 matching lines @@
     });
   };
 }
 
 /**
  * This class is purely here to scrape handwritten HTML documentation.
  * This scraped documentation will later be merged with the generated
  * HTML library.
  */
 class Htmldoc extends doc.Dartdoc {
-  String libraryComment;
+  doc.DocComment libraryComment;
 
   /**
    * Map from qualified type names to comments.
    */
-  Map<String, String> typeComments;
+  Map<String, doc.DocComment> typeComments;
 
   /**
    * Map from qualified member names to comments.
    */
-  Map<String, String> memberComments;
+  Map<String, doc.DocComment> memberComments;
 
   Htmldoc() {
-    typeComments = new Map<String, String>();
-    memberComments = new Map<String, String>();
+    typeComments = new Map<String, doc.DocComment>();
+    memberComments = new Map<String, doc.DocComment>();
   }
 
   // Suppress any actual writing to file.  This is only for analysis.
   void endFile() {
   }
 
   void write(String s) {
   }
 
-  String getRecordedLibraryComment(LibraryMirror library) {
+  doc.DocComment getRecordedLibraryComment(LibraryMirror library) {
     if (library.simpleName == HTML_LIBRARY_NAME) {
       return libraryComment;
     }
     return null;
   }
 
-  String getRecordedTypeComment(TypeMirror type) {
+  doc.DocComment getRecordedTypeComment(TypeMirror type) {
     if (typeComments.containsKey(type.qualifiedName)) {
       return typeComments[type.qualifiedName];
     }
     return null;
   }
 
-  String getRecordedMemberComment(MemberMirror member) {
+  doc.DocComment getRecordedMemberComment(MemberMirror member) {
     if (memberComments.containsKey(member.qualifiedName)) {
       return memberComments[member.qualifiedName];
     }
     return null;
   }
 
   // These methods are subclassed and used for internal processing.
   // Do not invoke outside of this class.
-  String getLibraryComment(LibraryMirror library) {
-    String comment = super.getLibraryComment(library);
+  doc.DocComment getLibraryComment(LibraryMirror library) {
+    doc.DocComment comment = super.getLibraryComment(library);
     libraryComment = comment;
     return comment;
   }
 
-  String getTypeComment(TypeMirror type) {
-    String comment = super.getTypeComment(type);
+  doc.DocComment getTypeComment(TypeMirror type) {
+    doc.DocComment comment = super.getTypeComment(type);
     recordTypeComment(type, comment);
     return comment;
   }
 
-  String getMethodComment(MethodMirror method) {
-    String comment = super.getMethodComment(method);
-    recordMemberComment(method, comment);
+  doc.DocComment getMemberComment(MemberMirror member) {
+    doc.DocComment comment = super.getMemberComment(member);
+    recordMemberComment(member, comment);
     return comment;
   }
 
-  String getFieldComment(FieldMirror field) {
-    String comment = super.getFieldComment(field);
-    recordMemberComment(field, comment);
-    return comment;
-  }
-
-  void recordTypeComment(TypeMirror type, String comment) {
-    if (comment != null && comment.contains('@domName')) {
+  void recordTypeComment(TypeMirror type, doc.DocComment comment) {
+    if (comment != null && comment.text.contains('@domName')) {
       // This is not a handwritten comment.
       return;
     }
     typeComments[type.qualifiedName] = comment;
   }
 
-  void recordMemberComment(MemberMirror member, String comment) {
-    if (comment != null && comment.contains('@domName')) {
+  void recordMemberComment(MemberMirror member, doc.DocComment comment) {
+    if (comment != null && comment.text.contains('@domName')) {
       // This is not a handwritten comment.
       return;
     }
     memberComments[member.qualifiedName] = comment;
   }
 }
 
 class Apidoc extends doc.Dartdoc {
   /** Big ball of JSON containing the scraped MDN documentation. */
   final Map mdn;
 
   final Htmldoc htmldoc;
 
   static const disqusShortname = 'dartapidocs';
 
   // A set of type names (TypeMirror.simpleName values) to ignore while
   // looking up information from MDN data.  TODO(eub, jacobr): fix up the MDN
   // import scripts so they run correctly and generate data that doesn't have
   // any entries that need to be ignored.
   static Set<String> _mdnTypeNamesToSkip = null;
 
   /**
    * The URL to the page on MDN that content was pulled from for the current
    * type being documented. Will be `null` if the type doesn't use any MDN
    * content.
    */
-  String mdnUrl;
+  String mdnUrl = null;
 
   Apidoc(this.mdn, this.htmldoc, Path outputDir, int mode,
          bool generateAppCache) {
     this.outputDir = outputDir;
     this.mode = mode;
     this.generateAppCache = generateAppCache;
 
     // Skip bad entries in the checked-in mdn/database.json:
     //  * UnknownElement has a top-level Gecko DOM page in German.
     if (_mdnTypeNamesToSkip == null)
@@ skipping 94 matching lines @@
   }
 
   void docLibrary(LibraryMirror library) {
     // TODO(rnystrom): Hackish. The IO libraries reference this but we don't
     // want it in the docs.
     if (library.simpleName == 'dart:nativewrappers') return;
     super.docLibrary(library);
   }
 
   /** Override definition from parent class to strip out annotation tags. */
-  String commentToHtml(String comment) {
-    return super.commentToHtml(
-        comment.replaceAll(const RegExp("@([a-zA-Z]+) ([^;]+)(?:;|\$)"), ''));
+  doc.DocComment createDocComment(String text,
+                                  [InterfaceMirror inheritedFrom]) {
+    String strippedText =
+        text.replaceAll(const RegExp("@([a-zA-Z]+) ([^;]+)(?:;|\$)"),
+                        '').trim();
+    if (strippedText.isEmpty()) return null;
+    return super.createDocComment(strippedText, inheritedFrom);
   }
 
-  String getLibraryComment(LibraryMirror library) {
+  doc.DocComment getLibraryComment(LibraryMirror library) {
     if (library.simpleName == HTML_LIBRARY_NAME) {
       return htmldoc.libraryComment;
     }
     return super.getLibraryComment(library);
   }
 
-  String getTypeComment(TypeMirror type) {
+  doc.DocComment getTypeComment(TypeMirror type) {
     return _mergeDocs(
         includeMdnTypeComment(type), super.getTypeComment(type),
         htmldoc.getRecordedTypeComment(type));
   }
 
-  String getMethodComment(MethodMirror method) {
+  doc.DocComment getMemberComment(MemberMirror member) {
     return _mergeDocs(
-        includeMdnMemberComment(method), super.getMethodComment(method),
-        htmldoc.getRecordedMemberComment(method));
+        includeMdnMemberComment(member), super.getMemberComment(member),
+        htmldoc.getRecordedMemberComment(member));
   }
 
-  String getFieldComment(FieldMirror field) {
-    return _mergeDocs(
-        includeMdnMemberComment(field), super.getFieldComment(field),
-        htmldoc.getRecordedMemberComment(field));
-  }
+  doc.DocComment _mergeDocs(MdnComment mdnComment,
+                            doc.DocComment fileComment,
+                            doc.DocComment handWrittenComment) {
+    // Prefer the hand-written comment first.
+    if (handWrittenComment !== null) return handWrittenComment;
 
-  bool isNonEmpty(String string) => (string != null) && (string.trim() != '');
-
-  String _mergeDocs(String mdnComment, String fileComment,
-                    String handWrittenComment) {
-    // Prefer the hand-written comment first.
-    if (isNonEmpty(handWrittenComment)) return handWrittenComment;
-
-    // Otherwise, prefer comment from the (possibly generated) Dart
-    // file.
-    if (isNonEmpty(fileComment)) return fileComment;
+    // Otherwise, prefer comment from the (possibly generated) Dart file.
+    if (fileComment !== null) return fileComment;
 
     // Finally, fallback on MDN if available.
-    if (isNonEmpty(mdnComment)) {
-      // Wrap it so we can highlight it and so we handle MDN scraped content
-      // that lacks a top-level block tag.
-      return '''
-          <div class="mdn">
-          $mdnComment
-          <div class="mdn-note"><a href="$mdnUrl">from MDN</a></div>
-          </div>
-          ''';
+    if (mdnComment !== null) {
+      mdnUrl = mdnComment.mdnUrl;
+      return mdnComment;
     }
 
     // We got nothing!
-    return '';
+    return null;
   }
 
   void docType(TypeMirror type) {
     // Track whether we've inserted MDN content into this page.
     mdnUrl = null;
 
     super.docType(type);
   }
 
   void writeTypeFooter() {
@@ skipping 18 matching lines @@
           <a href="$MDN">The Mozilla Developer Network</a>.
           </p>
           ''');
     }
   }
 
   /**
    * Gets the MDN-scraped docs for [type], or `null` if this type isn't
    * scraped from MDN.
    */
-  includeMdnTypeComment(TypeMirror type) {
+  MdnComment includeMdnTypeComment(TypeMirror type) {
     if (_mdnTypeNamesToSkip.contains(type.simpleName)) {
       print('Skipping MDN type ${type.simpleName}');
       return null;
     }
 
     var typeString = '';
     if (type.library.simpleName == HTML_LIBRARY_NAME) {
       // If it's an HTML type, try to map it to a base DOM type so we can find
       // the MDN docs.
       final domTypes = _diff.htmlTypesToDom[type.qualifiedName];
 
       // Couldn't find a DOM type.
       if ((domTypes == null) || (domTypes.length != 1)) return null;
 
       // Use the corresponding DOM type when searching MDN.
       // TODO(rnystrom): Shame there isn't a simpler way to get the one item
       // out of a singleton Set.
       typeString = domTypes.iterator().next();
     } else {
       // Not a DOM type.
       return null;
     }
 
     final mdnType = mdn[typeString];
     if (mdnType == null) return null;
     if (mdnType['skipped'] != null) return null;
+    if (mdnType['summary'] == null) return null;
+    if (mdnType['summary'].trim().isEmpty()) return null;
 
     // Remember which MDN page we're using so we can attribute it.
-    mdnUrl = mdnType['srcUrl'];
-    return mdnType['summary'];
+    return new MdnComment(mdnType['summary'], mdnType['srcUrl']);
   }
 
   /**
    * Gets the MDN-scraped docs for [member], or `null` if this type isn't
    * scraped from MDN.
    */
-  includeMdnMemberComment(MemberMirror member) {
+  MdnComment includeMdnMemberComment(MemberMirror member) {
     var library = findLibrary(member);
     var memberString = '';
     if (library.simpleName == HTML_LIBRARY_NAME) {
       // If it's an HTML type, try to map it to a DOM type name so we can find
       // the MDN docs.
       final domMembers = _diff.htmlToDom[member.qualifiedName];
 
       // Couldn't find a DOM type.
       if ((domMembers == null) || (domMembers.length != 1)) return null;
 
@@ skipping 18 matching lines @@
       var nameToFind = pieces[1];
       for (final candidateMember in mdnType['members']) {
         if (candidateMember['name'] == nameToFind) {
           mdnMember = candidateMember;
           break;
         }
       }
     }
 
     if (mdnMember == null) return null;
+    if (mdnMember['help'] == null) return null;
+    if (mdnMember['help'].trim().isEmpty()) return null;
 
     // Remember which MDN page we're using so we can attribute it.
-    mdnUrl = mdnType['srcUrl'];
-    return mdnMember['help'];
+    return new MdnComment(mdnMember['help'], mdnType['srcUrl']);
   }
 
   /**
    * Returns a link to [member], relative to a type page that may be in a
    * different library than [member].
    */
   String _linkMember(MemberMirror member) {
     final typeName = member.surroundingDeclaration.simpleName;
     var memberName = '$typeName.${member.simpleName}';
     if (member is MethodMirror && (member.isConstructor || member.isFactory)) {
       final separator = member.constructorName == '' ? '' : '.';
       memberName = 'new $typeName$separator${member.constructorName}';
     }
 
     return a(memberUrl(member), memberName);
   }
 }
+
+class MdnComment implements doc.DocComment {
+  final String mdnComment;
+  final String mdnUrl;
+
+  MdnComment(String this.mdnComment, String this.mdnUrl);
+
+  String get text => mdnComment;
+
+  InterfaceMirror get inheritedFrom => null;
+
+  String get html {
+    // Wrap the mdn comment so we can highlight it and so we handle MDN scraped
+    // content that lacks a top-level block tag.
+   return '''
+        <div class="mdn">
+        $mdnComment
+        <div class="mdn-note"><a href="$mdnUrl">from MDN</a></div>
+        </div>
+        ''';
+  }
+
+  String toString() => mdnComment;
+}