Dartdoc comments retrieved as metadata through dart2js mirrors.

sdk/lib/_internal/compiler/implementation/compiler.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 dart2js;
 
 /**
  * If true, print a warning for each method that was resolved, but not
  * compiled.
  */
@@ skipping 85 matching lines @@
   void dumpInferredTypes() {}
 
   ItemCompilationContext createItemCompilationContext() {
     return new ItemCompilationContext();
   }
 
   SourceString getCheckedModeHelper(DartType type) => null;
   void registerInstantiatedClass(ClassElement cls, Enqueuer enqueuer) {}
 }
 
+/**
+ * Key class used in [TokenKeyMap] in which the hash code for a token is based
+ * on the [charOffset].
+ */
+class TokenKey {
+  final Token token;
+  TokenKey(this.token);
+  int get hashCode => token.charOffset;
+  operator==(other) => other is TokenKey && token == other.token;
+}
+
+/**
+ * Map of tokens and the first associated comment.
+ *
+ * This implementation was chosen among several candidates for its space/time

[Andrei Mouravski, 2013/01/04 17:46:24]

Since it is an implementation detail, this rationale could go into a non doc
comment.

/// Map of tokens and the first associated comment.
/* 
 * This implementation...
 * ...
 */

[Johnni Winther, 2013/01/08 13:39:46]

Done.

+ * efficiency by empirical tests of running dartdoc on dartdoc itself. Time
+ * measurements for the use of [Compiler.commentMap]:
+ *
+ * 1) Using [TokenKey] as key (this class): ~80 msec
+ * 2) Using [TokenKey] as key + storing a separate map in each script: ~120 msec
+ * 3) Using [Token] as key in a [Map]: ~38000 msec
+ * 4) Storing comments is new field in [Token]: ~20 msec
+ *    (Abandoned due to the increased memory usage)
+ * 5) Storing comments in an [Expando]: ~14000 msec
+ * 6) Storing token/comments pairs in a linked list: ~5400 msec
+ */
+class TokenKeyMap {

[ahe, 2013/01/08 11:59:43]

This really is a TokenMap.

[Johnni Winther, 2013/01/08 13:39:46]

Done.

+  Map<TokenKey,Token> comments = new Map<TokenKey,Token>();
+
+  Token operator[] (Token key) {
+    return comments[new TokenKey(key)];
+  }
+
+  void operator[]= (Token key, Token value) {
+    comments[new TokenKey(key)] = value;
+  }
+}
+
 abstract class Compiler implements DiagnosticListener {
   final Map<String, LibraryElement> libraries;
   final Stopwatch totalCompileTime = new Stopwatch();
   int nextFreeClassId = 0;
   World world;
   String assembledCode;
   Types types;
 
+  /**
+   * Map from token to the first preceeding comment token.
+   */
+  final TokenKeyMap commentMap = new TokenKeyMap();
+
   final bool enableMinification;
   final bool enableTypeAssertions;
   final bool enableUserAssertions;
   final bool enableConcreteTypeInference;
   /**
    * The maximum size of a concrete type before it widens to dynamic during
    * concrete type inference.
    */
   final int maxConcreteTypeSize;
   final bool analyzeAll;
   final bool enableNativeLiveTypeAnalysis;
   final bool rejectDeprecatedFeatures;
   final bool checkDeprecationInSdk;
 
+  /**
+   * If [:true:], comment tokens are collected in [commentMap] during scanning.
+   */
+  final bool preserveComments;
+
   bool disableInlining = false;
 
   final Tracer tracer;
 
   CompilerTask measuredTask;
   Element _currentElement;
   LibraryElement coreLibrary;
   LibraryElement isolateLibrary;
   LibraryElement isolateHelperLibrary;
   LibraryElement jsHelperLibrary;
   LibraryElement interceptorsLibrary;
   LibraryElement foreignLibrary;
   LibraryElement mainApp;
 
   ClassElement objectClass;
   ClassElement closureClass;
   ClassElement dynamicClass;
   ClassElement boolClass;
   ClassElement numClass;
   ClassElement intClass;
   ClassElement doubleClass;
   ClassElement stringClass;
   ClassElement functionClass;
   ClassElement nullClass;
   ClassElement listClass;
   ClassElement typeClass;
   ClassElement mapClass;
   ClassElement jsInvocationMirrorClass;
+  /// Document class from dart:mirrors.
+  ClassElement documentClass;
   Element assertMethod;
   Element identicalFunction;
   Element functionApplyMethod;
   Element invokeOnMethod;
   Element createInvocationMirrorElement;
 
   Element get currentElement => _currentElement;
   withCurrentElement(Element element, f()) {
     Element old = currentElement;
     _currentElement = element;
@@ skipping 74 matching lines @@
             this.enableConcreteTypeInference: false,
             this.maxConcreteTypeSize: 5,
             this.enableMinification: false,
             this.enableNativeLiveTypeAnalysis: false,
             bool emitJavaScript: true,
             bool generateSourceMap: true,
             bool disallowUnsafeEval: false,
             this.analyzeAll: false,
             this.rejectDeprecatedFeatures: false,
             this.checkDeprecationInSdk: false,
+            this.preserveComments: false,
             List<String> strips: const []})
       : libraries = new Map<String, LibraryElement>(),
         progress = new Stopwatch() {
     progress.start();
     world = new World(this);
 
     closureMapping.ClosureNamer closureNamer;
     if (emitJavaScript) {
       js_backend.JavaScriptBackend jsBackend =
           new js_backend.JavaScriptBackend(this, generateSourceMap,
@@ skipping 236 matching lines @@
     identicalFunction = coreLibrary.find(const SourceString('identical'));
 
     initializeSpecialClasses();
 
     functionClass.ensureResolved(this);
     functionApplyMethod =
         functionClass.lookupLocalMember(const SourceString('apply'));
     jsInvocationMirrorClass.ensureResolved(this);
     invokeOnMethod = jsInvocationMirrorClass.lookupLocalMember(
         const SourceString('invokeOn'));
+
+    if (preserveComments) {
+      var uri = new Uri.fromComponents(scheme: 'dart', path: 'mirrors');
+      LibraryElement libraryElement =
+          libraryLoader.loadLibrary(uri, null, uri);
+      documentClass = libraryElement.find(const SourceString('Comment'));
+    }
   }
 
   void importHelperLibrary(LibraryElement library) {
     if (jsHelperLibrary != null) {
       libraryLoader.importLibrary(library, jsHelperLibrary, null);
     }
   }
 
   /**
    * Get an [Uri] pointing to a patch for the dart: library with
@@ skipping 375 matching lines @@
   }
 
   // TODO(karlklose): split into findHelperFunction and findHelperClass and
   // add a check that the element has the expected kind.
   Element findHelper(SourceString name)
       => jsHelperLibrary.findLocal(name);
   Element findInterceptor(SourceString name)
       => interceptorsLibrary.findLocal(name);
 
   bool get isMockCompilation => false;
+
+  Token processAndStripComments(Token currentToken) {
+    Token firstToken = currentToken;
+    Token prevToken;
+    while (currentToken.kind != EOF_TOKEN) {
+      if (identical(currentToken.kind, COMMENT_TOKEN)) {
+        Token firstCommentToken = currentToken;
+        while (identical(currentToken.kind, COMMENT_TOKEN)) {
+          currentToken = currentToken.next;
+        }
+        commentMap[currentToken] = firstCommentToken;
+        if (prevToken == null) {
+          firstToken = currentToken;
+        } else {
+          prevToken.next = currentToken;
+        }
+      }
+      prevToken = currentToken;
+      currentToken = currentToken.next;
+    }
+    return firstToken;
+  }
 }
 
 class CompilerTask {
   final Compiler compiler;
   final Stopwatch watch;
 
   CompilerTask(this.compiler) : watch = new Stopwatch();
 
   String get name => 'Unknown task';
   int get timing => watch.elapsedMilliseconds;
@@ skipping 76 matching lines @@
   // TODO(johnniwinther): Use [spannable] and [message] to provide better
   // information on assertion errors.
   if (condition is Function){
     condition = condition();
   }
   if (spannable == null || !condition) {
     throw new SpannableAssertionFailure(spannable, message);
   }
   return true;
 }