pkg/dartdoc/lib/src/dartdoc/comment_map.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.

part of dartdoc;

/**
 * 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 {
  /**
   * Maps from (filename, pos) to doc comment preceding the token at that
   * position.
   */
  Map<String, Map<int, String>> _comments;

  /** Doc comments before #library() directives. */
  Map<String, String> _libraryComments;

  CommentMap()
    : _comments = <String, Map<int, String>>{},
      _libraryComments = <String, String>{};

  /**
   * Finds the doc comment preceding the given source span, if there is one.
   *
   * If a comment is returned, it is guaranteed to be non-empty.
   */
  String find(SourceLocation span) {
    if (span == null) return null;

    _ensureFileParsed(span.source);
    String comment = _comments[span.source.uri.toString()][span.start];
    assert(comment == null || !comment.trim().isEmpty);
    return comment;
  }

  /**
   * Finds the doc comment associated with the `#library` directive for the
   * given file.
   *
   * If a comment is returned, it is guaranteed to be non-empty.
   */
  String findLibrary(Source source) {
    _ensureFileParsed(source);
    String comment = _libraryComments[source.uri.toString()];
    assert(comment == null || !comment.trim().isEmpty);
    return comment;
  }

  _ensureFileParsed(Source source) {
    _comments.putIfAbsent(source.uri.toString(), () =>
        _parseComments(source));
  }

  _parseComments(Source source) {
    final comments = new Map<int, String>();

    final scanner = new dart2js.StringScanner(source.text,
                                              includeComments: true);
    var lastComment = null;

    var token = scanner.tokenize();
    while (token.kind != dart2js.EOF_TOKEN) {
      if (token.kind == dart2js.COMMENT_TOKEN) {
        final text = token.slowToString();
        if (text.startsWith('/**')) {
          // Remember that we've encountered a doc comment.
          lastComment = stripComment(token.slowToString());
        } else if (text.startsWith('///')) {
          var line = text.substring(3);
          // Allow a leading space.
          if (line.startsWith(' ')) line = line.substring(1);
          if (lastComment == null) {
            lastComment = line;
          } else {
            lastComment = '$lastComment$line';
          }
        }
      } else if (token.kind == dart2js.HASH_TOKEN) {
        // Look for #library() to find the library comment.
        final next = token.next;
        if ((lastComment != null) && (next.stringValue == 'library')) {
          _libraryComments[source.uri.toString()] = lastComment;
          lastComment = null;
        }
      } else if (lastComment != null) {
        if (!lastComment.trim().isEmpty) {
          // We haven't attached the last doc comment to something yet, so stick
          // it to this token.
          comments[token.charOffset] = lastComment;
        }
        lastComment = null;
      }
      token = token.next;
    }

    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 (var line in comment.split('\n')) {
      line = line.trim();
      if (line.startsWith('/**')) line = line.substring(3);
      if (line.endsWith('*/')) line = line.substring(0, line.length - 2);
      line = line.trim();
      if (line.startsWith('* ')) {
        line = line.substring(2);
      } else if (line.startsWith('*')) {
        line = line.substring(1);
      }

      buf.add(line);
      buf.add('\n');
    }

    return buf.toString();
  }
}