Refactor dartdoc into a class. Use method overriding to extend.

utils/dartdoc/comment_map.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.
+
+/**
+ * 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 "class" token below.
+ */
+class CommentMap {
+  Map<String, Map<int, String>> _comments;

[nweiz, 2011/12/15 19:39:04]

Mention that this is a map from filename -> position -> comment.

[Bob Nystrom, 2011/12/15 20:20:11]

Done.

+
+  /** Doc comments before #library() directives. */
+  Map<String, String> _libraryComments;
+
+  CommentMap()
+    : _comments = <Map<int, String>>{},
+      _libraryComments = <String>{};
+
+  /** Finds the doc comment preceding the given source span, if there is one. */
+  String find(SourceSpan span) {
+    if (span == null) return null;
+
+    _ensureFileParsed(span.file);
+    final comment = _comments[span.file.filename][span.start];
+    if (comment == null) return '';
+    return comment;
+  }
+
+  /**
+   * Finds the doc comment associated with the `#library` directive for the
+   * given file.
+   */
+  String findLibrary(SourceFile file) {
+    _ensureFileParsed(file);
+    final comment = _libraryComments[file.filename];
+    if (comment == null) return '';
+    return comment;
+  }
+
+  _ensureFileParsed(SourceFile file) {
+    _comments.putIfAbsent(file.filename, () => _parseComments(file));
+  }
+
+  _parseComments(SourceFile file) {
+    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;
+        if (text.startsWith('/**')) {
+          // Remember that we've encountered a doc comment.
+          lastComment = stripComment(token.text);
+        } else if (text.startsWith('///')) {
+          var line = text.substring(3, text.length);

[nweiz, 2011/12/15 19:39:04]

text.substring(3) is equivalent to text.substring(3, text.length), here and
elsewhere.

[Bob Nystrom, 2011/12/15 20:20:11]

Done, though I'm not sure how that worked before. We don't have optional
positional parameters, do we?

[nweiz, 2011/12/15 20:54:07]

I'm pretty sure optional parameters can be used positionally or by name.

+          // Allow a leading space.
+          if (line.startsWith(' ')) line = line.substring(1, text.length);

[nweiz, 2011/12/15 19:39:04]

This probably wants to be line.length, not text.length, right? Although in that
case it actually wants to be line.substring(1).

[Bob Nystrom, 2011/12/15 20:20:11]

Done.

+          if (lastComment == null) {
+            lastComment = line;
+          } else {
+            lastComment = '$lastComment$line';
+          }
+        }
+      } else if (token.kind == TokenKind.WHITESPACE) {
+        // Ignore whitespace tokens.
+      } else if (token.kind == TokenKind.HASH) {
+        // Look for #library() to find the library comment.
+        final next = tokenizer.next();
+        if ((lastComment != null) && (next.kind == TokenKind.LIBRARY)) {
+          _libraryComments[file.filename] = lastComment;
+          lastComment = null;
+        }
+      } else {
+        if (lastComment != null) {
+          // We haven't attached the last doc comment to something yet, so stick
+          // it to this token.
+          comments[token.start] = lastComment;
+          lastComment = null;
+        }
+      }
+    }
+
+    return comments;
+  }
+
+  /**
+   * Pulls the raw text out of a doc comment (i.e. removes the comment
+   * characters).
+   */
+  stripComment(String comment) {
+    StringBuffer buf = new StringBuffer();
+
+    for (final line in comment.split('\n')) {
+      line = line.trim();
+      if (line.startsWith('/**')) line = line.substring(3, line.length);
+      if (line.endsWith('*/')) line = line.substring(0, line.length - 2);
+      line = line.trim();
+      if (line.startsWith('* ')) {
+        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();
+  }
+}