Add a script to generate HTML and DOM docs with cross-links to one another.

utils/dartdoc/dartdoc.dart

 // Copyright (c) 2011, 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 use it, from this directory, run:
  *
  *     $ dartdoc <path to .dart file>
  *
  * This will create a "docs" directory with the docs for your libraries. To
@@ skipping 36 matching lines @@
 
 /**
  * The cached lookup-table to associate doc comments with spans. The outer map
  * is from filenames to doc comments in that file. The inner map maps from the
  * token positions to doc comments. Each position is the starting offset of the
  * next non-comment token *following* the doc comment. For example, the position
  * for this comment would be the position of the "Map" token below.
  */
 Map<String, Map<int, String>> _comments;
 
+/** A callback that returns additional Markdown documentation for a type. */
+typedef String TypeDocumenter(Type type);
+
+/** A list of callbacks registered for documenting types. */
+List<TypeDocumenter> _typeDocumenters;
+
+/** A callback that returns additional Markdown documentation for a method. */
+typedef String MethodDocumenter(MethodMember method);
+
+/** A list of callbacks registered for documenting methods. */
+List<MethodDocumenter> _methodDocumenters;
+
+/** A callback that returns additional Markdown documentation for a field. */
+typedef String FieldDocumenter(FieldMember field);
+
+/** A list of callbacks registered for documenting fields. */
+List<FieldDocumenter> _fieldDocumenters;
+
 int _totalLibraries = 0;
 int _totalTypes = 0;
 int _totalMembers = 0;
 
 /**
  * Run this from the `utils/dartdoc` directory.
  */
 void main() {
   // The entrypoint of the library to generate docs for.
   final entrypoint = process.argv[2];
 
   // Parse the dartdoc options.
   for (int i = 3; i < process.argv.length; i++) {
     final arg = process.argv[i];
     switch (arg) {
       case '--no-code':
         includeSource = false;
         break;
 
       default:
         print('Unknown option: $arg');
     }
   }
 
   files = new NodeFileSystem();
   parseOptions('../../frog', [] /* args */, files);
-  options.dietParse = true;
+  initializeWorld(files);
+
+  final elapsed = time(() {
+    initializeDartDoc();
+    document(entrypoint);
+  });
+
+  printStats();
+}
+
+void initializeDartDoc() {
+  _comments = <Map<int, String>>{};
+  _typeDocumenters = <TypeDocumenter>[];
+  _methodDocumenters = <MethodDocumenter>[];
+  _fieldDocumenters = <FieldDocumenter>[];
 
   // Patch in support for [:...:]-style code to the markdown parser.
   // TODO(rnystrom): Markdown already has syntax for this. Phase this out?
   md.InlineParser.syntaxes.insertRange(0, 1,
       new md.CodeSyntax(@'\[\:((?:.|\n)*?)\:\]'));
 
   md.setImplicitLinkResolver(resolveNameReference);
+}
 
-  final elapsed = time(() {
-    initializeDartDoc();
-
-    initializeWorld(files);
+document(String entrypoint) {
+  try {
+    var oldDietParse = options.dietParse;
+    options.dietParse = true;
 
     // Handle the built-in entrypoints.
     switch (entrypoint) {
       case 'corelib':
         world.getOrAddLibrary('dart:core');
         world.getOrAddLibrary('dart:coreimpl');
         world.process();
         break;
 
       case 'dom':
@@ skipping 16 matching lines @@
         world.processDartScript(entrypoint);
     }
 
     world.resolveAll();
 
     // Generate the docs.
     docIndex();
     for (final library in world.libraries.getValues()) {
       docLibrary(library);
     }
-  });
-
-  print('Documented $_totalLibraries libraries, $_totalTypes types, and ' +
-        '$_totalMembers members in ${elapsed}msec.');
+  } finally {
+    options.dietParse = oldDietParse;
+  }
 }
 
-void initializeDartDoc() {
-  _comments = <String, Map<int, String>>{};
+printStats() {
+  print('Documented $_totalLibraries libraries, $_totalTypes types, and ' +
+      '$_totalMembers members in ${elapsed}msec.');
 }
 
 writeHeader(String title) {
   writeln(
       '''
       <!DOCTYPE html>
       <html>
       <head>
       <meta charset="utf-8">
       <title>$title</title>
@@ skipping 82 matching lines @@
       write('<div class="$icon"></div><strong>${typeName(type)}</strong>');
     } else {
       write(a(typeUrl(type), '<div class="$icon"></div>${typeName(type)}'));
     }
 
     writeln('</li>');
   }
   writeln('</ul>');
 }
 
+String _runDocumenters(var item, List<Function> documenters) =>
+  Strings.join(map(documenters, (doc) => doc(item)), '\n\n');
+
 docLibrary(Library library) {
   _totalLibraries++;
   _currentLibrary = library;
   _currentType = null;
 
   startFile(libraryUrl(library));
   writeHeader(library.name);
   writeln('<h1>Library <strong>${library.name}</strong></h1>');
 
   // Look for a comment for the entire library.
@@ skipping 63 matching lines @@
   writeHeader('Library ${type.library.name} / $typeTitle');
   writeln(
       '''
       <h1>${a(libraryUrl(type.library),
             "Library <strong>${type.library.name}</strong>")}</h1>
       <h2>${type.isClass ? "Class" : "Interface"}
           <strong>${typeName(type, showBounds: true)}</strong></h2>
       ''');
 
   docInheritance(type);
-  docCode(type.span);
+  docCode(type.span, _runDocumenters(type, _typeDocumenters));
   docConstructors(type);
   docMembers(type);
 
   writeFooter();
   endFile();
 }
 
 void docMembers(Type type) {
   // Collect the different kinds of members.
   final methods = [];
@@ skipping 37 matching lines @@
 
   if (isSubclass ||
       (type.interfaces != null && type.interfaces.length > 0) ||
       (factory != null)) {
     writeln('<p>');
 
     if (isSubclass) {
       write('Extends ${typeReference(type.parent)}. ');
     }
 
-    if (type.interfaces != null) {
-      switch (type.interfaces.length) {
-        case 0:
-          // Do nothing.
-          break;
-
-        case 1:
-          write('Implements ${typeReference(type.interfaces[0])}. ');
-          break;
-
-        case 2:
-          write('''Implements ${typeReference(type.interfaces[0])} and
-              ${typeReference(type.interfaces[1])}. ''');
-          break;
-
-        default:
-          write('Implements ');
-          for (final i = 0; i < type.interfaces.length; i++) {
-            write('${typeReference(type.interfaces[i])}');
-            if (i < type.interfaces.length - 2) {
-              write(', ');
-            } else if (i < type.interfaces.length - 1) {
-              write(', and ');
-            }
-          }
-          write('. ');
-          break;
-      }
+    if (type.interfaces != null && type.interfaces.length > 0) {
+      var interfaceStr = joinWithCommas(map(type.interfaces, typeReference));
+      write('Implements ${interfaceStr}. ');
     }
 
     if (factory != null) {
       write('Has factory class ${typeReference(factory)}.');
     }
   }
 }
 
 /** Document the constructors for [Type], if any. */
 docConstructors(Type type) {
@@ skipping 61 matching lines @@
     write('.');
     write(constructorName);
   }
 
   docParamList(type, method);
 
   write(''' <a class="anchor-link" href="#${memberAnchor(method)}"
             title="Permalink to ${typeName(type)}.$name">#</a>''');
   writeln('</h4>');
 
-  docCode(method.span, showCode: true);
+  docCode(method.span, _runDocumenters(method, _methodDocumenters),
+      showCode: true);
 
   writeln('</div>');
 }
 
 docParamList(Type enclosingType, MethodMember member) {
   write('(');
   bool first = true;
   bool inOptionals = false;
   for (final parameter in member.parameters) {
     if (!first) write(', ');
@@ skipping 47 matching lines @@
 
   annotateType(type, field.type);
   write(
       '''
       <strong>${field.name}</strong> <a class="anchor-link"
           href="#${memberAnchor(field)}"
           title="Permalink to ${typeName(type)}.${field.name}">#</a>
       </h4>
       ''');
 
-  docCode(field.span, showCode: true);
+  docCode(field.span, _runDocumenters(field, _fieldDocumenters),
+      showCode: true);
   writeln('</div>');
 }
 
 /**
  * Creates a hyperlink. Handles turning the [href] into an appropriate relative
  * path from the current file.
  */
 String a(String href, String contents, [String class]) {
   final css = class == null ? '' : ' class="$class"';
   return '<a href="${relativePath(href)}"$css>$contents</a>';
@@ skipping 167 matching lines @@
   // * Type parameters of the enclosing type.
 
   return new md.Element.text('code', name);
 }
 
 /**
  * Documents the code contained within [span]. Will include the previous
  * Dartdoc associated with that span if found, and will include the syntax
  * highlighted code itself if desired.
  */
-docCode(SourceSpan span, [bool showCode = false]) {
+docCode(SourceSpan span, String extraMarkdown, [bool showCode = false]) {
   if (span == null) return;
 
   writeln('<div class="doc">');
   final comment = findComment(span);
   if (comment != null) {
-    writeln(md.markdownToHtml(comment));
+    writeln(md.markdownToHtml('${comment}\n\n${extraMarkdown}'));
+  } else {
+    writeln(md.markdownToHtml(extraMarkdown));
   }
 
   if (includeSource && showCode) {
     writeln('<pre class="source">');
     write(formatCode(span));
     writeln('</pre>');
   }
 
   writeln('</div>');
 }
 
 /** Finds the doc comment preceding the given source span, if there is one. */
 findComment(SourceSpan span) => findCommentInFile(span.file, span.start);
 
 /** Finds the doc comment preceding the given source span, if there is one. */
 findCommentInFile(SourceFile file, int position) {
   // Get the doc comments for this file.
   final fileComments = _comments.putIfAbsent(file.filename,
     () => parseDocComments(file));
 
   return fileComments[position];
 }
 
 parseDocComments(SourceFile file) {
-  final comments = <int, String>{};
+  final comments = new Map<int, String>();
 
   final tokenizer = new Tokenizer(file, false);
   var lastComment = null;
 
   while (true) {
     final token = tokenizer.next();
     if (token.kind == TokenKind.END_OF_FILE) break;
 
     if (token.kind == TokenKind.COMMENT) {
       final text = token.text;
@@ skipping 72 matching lines @@
       line = line.substring(2, line.length);
     } else if (line.startsWith('*')) {
       line = line.substring(1, line.length);
     }
 
     buf.add(line);
     buf.add('\n');
   }
 
   return buf.toString();
-}
+}
+
+/** Register a callback to add additional documentation to a type. */
+addTypeDocumenter(TypeDocumenter fn) => _typeDocumenters.add(fn);
+
+/** Register a callback to add additional documentation to a method. */
+addMethodDocumenter(MethodDocumenter fn) => _methodDocumenters.add(fn);
+
+/** Register a callback to add additional documentation to a field. */
+addFieldDocumenter(FieldDocumenter fn) => _fieldDocumenters.add(fn);