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

utils/dartdoc/dartdoc.dart

Index: utils/dartdoc/dartdoc.dart
diff --git a/utils/dartdoc/dartdoc.dart b/utils/dartdoc/dartdoc.dart
index b12d4e4a097bbee92c95f7359b1f33b6440e1081..5523f30f5e2fba9e54646c449575f7b4cb6b639c 100644
--- a/utils/dartdoc/dartdoc.dart
+++ b/utils/dartdoc/dartdoc.dart
@@ -54,6 +54,24 @@ Member _currentMember;
  */
 Map<String, Map<int, String>> _comments;
 
+/** A callback that returns additional Markdown documentation for a type. */
+typedef String DocTypeFunction(Type type);
+
+/** A list of callbacks registered for documenting types. */
+List<DocTypeFunction> _docTypeFns;

[Bob Nystrom, 2011/12/06 23:11:23]

How about "Documenter" instead of "Function" and "Fn" here and elsewhere?

[nweiz, 2011/12/07 19:26:56]

Done.

+
+/** A callback that returns additional Markdown documentation for a method. */
+typedef String DocMethodFunction(MethodMember method);
+
+/** A list of callbacks registered for documenting methods. */
+List<DocMethodFunction> _docMethodFns;
+
+/** A callback that returns additional Markdown documentation for a field. */
+typedef String DocFieldFunction(FieldMember field);
+
+/** A list of callbacks registered for documenting fields. */
+List<DocFieldFunction> _docFieldFns;
+
 int _totalLibraries = 0;
 int _totalTypes = 0;
 int _totalMembers = 0;
@@ -136,7 +154,11 @@ void main() {
 }
 
 void initializeDartDoc() {
+  if (_comments != null) return;
   _comments = <String, Map<int, String>>{};
+  _docTypeFns = <DocTypeFunction>[];
+  _docMethodFns = <DocMethodFunction>[];
+  _docFieldFns = <DocFieldFunction>[];
 }
 
 writeHeader(String title) {
@@ -234,6 +256,9 @@ docLibraryNavigation(Library library) {
   writeln('</ul>');
 }
 
+String _callbacks(var item, List<Function> callbacks) =>

[Bob Nystrom, 2011/12/06 23:11:23]

Just because you *can* use a functional style doesn't mean you *must*. :)

Personally, I don't use => if I have to wrap to the next line, even though that
does mean needing a "return". Like it or not, Dart is statement-oriented and I
don't think we should fight that that hard.

Also, this name doesn't really illuminate. Maybe _runDocumenters?

[nweiz, 2011/12/07 19:26:56]

I'll concede that Member#hashCode and #== were a bit overboard, but this is a
pretty simple one-liner. I think it reads fine as-is.
Done.

+  Strings.join(map(callbacks, (cb) => cb(item)), '\n\n');
+
 docLibrary(Library library) {
   _totalLibraries++;
   _currentLibrary = library;
@@ -294,7 +319,7 @@ docType(Type type) {
       ''');
 
   docInheritance(type);
-  docCode(type.span);
+  docCode(type.span, _callbacks(type, _docTypeFns));
   docConstructors(type);
   docMembers(type);
 
@@ -461,7 +486,7 @@ docMethod(Type type, MethodMember method, [String constructorName = null]) {
             title="Permalink to ${typeName(type)}.$name">#</a>''');
   writeln('</h4>');
 
-  docCode(method.span, showCode: true);
+  docCode(method.span, _callbacks(method, _docMethodFns), showCode: true);
 
   writeln('</div>');
 }
@@ -496,7 +521,7 @@ docField(Type type, FieldMember field) {
       </h4>
       ''');
 
-  docCode(field.span, showCode: true);
+  docCode(field.span, _callbacks(field, _docFieldFns), showCode: true);
   writeln('</div>');
 }
 
@@ -625,13 +650,15 @@ md.Node resolveNameReference(String name) {
  * 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 extraDocs, [bool showCode = false]) {

[Bob Nystrom, 2011/12/06 23:11:23]

"extraMarkdown"

We need to make it clear that this happens before md->html.

[nweiz, 2011/12/07 19:26:56]

Done.

   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${extraDocs}'));
+  } else {
+    writeln(md.markdownToHtml(extraDocs));
   }
 
   if (includeSource && showCode) {
@@ -749,4 +776,13 @@ stripComment(comment) {
   }
 
   return buf.toString();
-}
+}
+
+/** Register a callback to add additional documentation to a type. */
+registerTypeCallback(DocTypeFunction fn) => _docTypeFns.add(fn);

[Bob Nystrom, 2011/12/06 23:11:23]

I'd name this "add" instead of "register" to make it clear that it doesn't
replace a previously added one. Also, it isn't really clear what this callback
does for the type.

Maybe addTypeDocumenter(TypeDocumenter documenter)?

[nweiz, 2011/12/07 19:26:56]

Done.

+
+/** Register a callback to add additional documentation to a method. */
+registerMethodCallback(DocMethodFunction fn) => _docMethodFns.add(fn);
+
+/** Register a callback to add additional documentation to a field. */
+registerFieldCallback(DocFieldFunction fn) => _docFieldFns.add(fn);