Modify apidoc to prefer handwritten HTML5 docs over those in MDN or generated code.

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 86 matching lines @@
   initializeWorld(files);
 
   print('Parsing MDN data...');
   final mdnFile = new File('${doc.scriptDir}/mdn/database.json');
   final mdn = JSON.parse(mdnFile.readAsTextSync());
 
   print('Cross-referencing dart:html...');
   HtmlDiff.initialize();
   _diff = new HtmlDiff(printWarnings:false);
   _diff.run();
+
+  // Process handwritten HTML documentation.
+  world.reset();
+  world.getOrAddLibrary('${doc.scriptDir}/../../lib/html/doc/html.dartdoc');
+  world.process();
+  final htmldoc = new Htmldoc();
+  htmldoc.document();

[Bob Nystrom, 2012/06/11 19:31:19]

This still generates the output files, doesn't it? That will waste a decent
amount of time.

The easiest hack to fix this will be to override endFile(), write(), and
writeln() in Htmldoc to have them do nothing.

[vsm, 2012/06/11 20:51:01]

Thanks - done.

On 2012/06/11 19:31:19, Bob Nystrom wrote:

+  print('Processing handwritten HTML documentation...');
+
+  // Process libraries.
   world.reset();
 
   // Add all of the core libraries.
   world.getOrAddLibrary('dart:core');
   world.getOrAddLibrary('dart:coreimpl');
   world.getOrAddLibrary('dart:crypto');
   world.getOrAddLibrary('dart:html');
   world.getOrAddLibrary('dart:io');
   world.getOrAddLibrary('dart:isolate');
   world.getOrAddLibrary('dart:json');
   world.getOrAddLibrary('${doc.scriptDir}/../../lib/math/math.dart');
   world.getOrAddLibrary('${doc.scriptDir}/../../lib/unittest/unittest.dart');
   world.getOrAddLibrary('dart:uri');
   world.getOrAddLibrary('dart:utf');
   world.process();
 
   print('Generating docs...');
-  final apidoc = new Apidoc(mdn, outputDir, mode, generateAppCache);
+  final apidoc = new Apidoc(mdn, htmldoc, outputDir, mode, generateAppCache);
 
   Futures.wait([scriptCompiled, copiedStatic, copiedApiDocStatic]).then((_) {
     apidoc.document();
   });
 }
 
+/**
+ * This class is purely here to scrape handwritten HTML documentation.
+ * This scraped documentation will later be merged with the generated
+ * HTML library.

[Bob Nystrom, 2012/06/11 19:31:19]

Hackish, but works.

I would leave a comment explaining that it works this way because frog is
relying on global internal state.

[vsm, 2012/06/11 20:51:01]

Comment added at the reset above.

On 2012/06/11 19:31:19, Bob Nystrom wrote:

+ */
+class Htmldoc extends doc.Dartdoc {
+  String libraryComment;
+  Map<String, String> typeComments;
+  Map<String, Map<String, String>> memberComments;
+
+  Htmldoc() {
+    typeComments = new Map<String, String>();
+    memberComments = new Map<String, Map<String, String>>();
+  }
+
+  String getRecordedLibraryComment(Library library) {
+    if (library.name == 'html') {
+      return libraryComment;
+    }
+    return null;
+  }
+
+  String getRecordedTypeComment(Type type) {
+    if (type.library.name == 'html') {
+      if (typeComments.containsKey(type.name)) {
+        return typeComments[type.name];
+      }
+    }
+    return null;
+  }
+
+  String getRecordedMemberComment(Member member) {
+    if (member.library.name == 'html') {
+      String typeName;
+      if (member.declaringType != null) {
+        typeName = member.declaringType.name;
+      }
+      if (typeName == null) {
+        typeName = '';
+      }
+      if (memberComments.containsKey(typeName)) {
+        Map<String, String> memberMap = memberComments[typeName];
+        if (memberMap.containsKey(member.name)) {
+          return memberMap[member.name];
+        }
+      }
+    }
+    return null;
+  }
+
+  // These methods are subclassed and used for internal processing.
+  // Do not invoke outside of this class.
+  String getLibraryComment(Library library) {
+    String comment = super.getLibraryComment(library);
+    libraryComment = comment;
+    return comment;
+  }
+
+  String getTypeComment(Type type) {
+    String comment = super.getTypeComment(type);
+    recordTypeComment(type, comment);
+    return comment;
+  }
+
+  String getMethodComment(MethodMember method) {
+    String comment = super.getMethodComment(method);
+    recordMemberComment(method, comment);
+    return comment;
+  }
+
+  String getFieldComment(FieldMember field) {
+    String comment = super.getFieldComment(field);
+    recordMemberComment(field, comment);
+    return comment;
+  }
+
+  void recordTypeComment(Type type, String comment) {
+    if (comment != null && comment.contains('@domName')) {
+      // This is not a handwritten comment.
+      return;
+    }
+    typeComments[type.name] = comment;
+  }
+
+  void recordMemberComment(Member member, String comment) {
+    if (comment != null && comment.contains('@domName')) {
+      // This is not a handwritten comment.
+      return;
+    }
+    String typeName = member.declaringType.name;
+    if (typeName == null)
+      typeName = '';
+    if (!memberComments.containsKey(typeName)) {
+      memberComments[typeName] = new Map<String, String>();
+    }
+    Map<String, String> memberMap = memberComments[typeName];
+    memberMap[member.name] = comment;
+  }
+}
+
 class Apidoc extends doc.Dartdoc {
   /** Big ball of JSON containing the scraped MDN documentation. */
   final Map mdn;
 
+  final Htmldoc htmldoc;
+
   static final disqusShortname = 'dartapidocs';
 
   /**
    * 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;
 
-  Apidoc(this.mdn, String outputDir, int mode, bool generateAppCache) {
+  Apidoc(this.mdn, this.htmldoc, String outputDir, int mode,
+         bool generateAppCache) {
     this.outputDir = outputDir;
     this.mode = mode;
     this.generateAppCache = generateAppCache;
 
     mainTitle = 'Dart API Reference';
     mainUrl = 'http://dartlang.org';
 
     final note    = 'http://code.google.com/policies.html#restrictions';
     final cca     = 'http://creativecommons.org/licenses/by/3.0/';
     final bsd     = 'http://code.google.com/google_bsd_license.html';
@@ skipping 91 matching lines @@
     if (library.name == '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]+) ([^;]+)(?:;|\$)"), ''));
   }
 
+  String getLibraryComment(Library library) {
+    if (library.name == 'html') {
+      return htmldoc.libraryComment;
+    }
+    return super.getLibraryComment(library);
+  }
+
   String getTypeComment(Type type) {
     return _mergeDocs(
-        includeMdnTypeComment(type), super.getTypeComment(type));
+        includeMdnTypeComment(type), super.getTypeComment(type),
+        htmldoc.getRecordedTypeComment(type));
   }
 
   String getMethodComment(MethodMember method) {
     return _mergeDocs(
-        includeMdnMemberComment(method), super.getMethodComment(method));
+        includeMdnMemberComment(method), super.getMethodComment(method),
+        htmldoc.getRecordedMemberComment(method));
   }
 
   String getFieldComment(FieldMember field) {
     return _mergeDocs(
-        includeMdnMemberComment(field), super.getFieldComment(field));
+        includeMdnMemberComment(field), super.getFieldComment(field),
+        htmldoc.getRecordedMemberComment(field));
   }
 
   bool isNonEmpty(String string) => (string != null) && (string.trim() != '');
 
-  String _mergeDocs(String mdnComment, String dartComment) {
+  String _mergeDocs(String mdnComment, String dartComment, String override) {
+    // Prefer override first.
+    if (isNonEmpty(override)) return override;
+
     // Prefer hand-written Dart comments over stuff from MDN.

[Bob Nystrom, 2012/06/11 19:31:19]

This comment is confusing now. How about changing the params too:

mdnComment, generatedComment, handWrittenComment

And then remove this comment?

[vsm, 2012/06/11 20:51:01]

Done.  I used "fileComment" instead of "generatedComment" (and added some
explanation) as not all files are generated.

On 2012/06/11 19:31:19, Bob Nystrom wrote:

     if (isNonEmpty(dartComment)) return dartComment;
 
     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>
@@ skipping 123 matching lines @@
     if (member.isConstructor || member.isFactory) {
       final separator = member.constructorName == '' ? '' : '.';
       memberName = 'new $typeName$separator${member.constructorName}';
     } else if (member.name.startsWith(GET_PREFIX)) {
       memberName = '$typeName.${member.name.substring(GET_PREFIX.length)}';
     }
 
     return a(memberUrl(member), memberName);
   }
 }