Dartdoc comments retrieved as metadata through dart2js mirrors.

sdk/lib/_internal/compiler/implementation/mirrors/dart2js_mirror.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.
 
 library mirrors_dart2js;
 
 import 'dart:io';
 import 'dart:uri';
 
 import '../../compiler.dart' as diagnostics;
 import '../elements/elements.dart';
 import '../resolution/resolution.dart' show ResolverTask, ResolverVisitor;
 import '../apiimpl.dart' as api;
-import '../scanner/scannerlib.dart';
+import '../scanner/scannerlib.dart' hide SourceString;
 import '../ssa/ssa.dart';
 import '../dart2jslib.dart';
 import '../filenames.dart';
 import '../source_file.dart';
 import '../tree/tree.dart';
 import '../util/util.dart';
 import '../util/uri_extras.dart';
 import '../dart2js.dart';
 import '../util/characters.dart';
 
@@ skipping 359 matching lines @@
                      [Path packageRoot, List<String> opts = const <String>[]])
       : cwd = getCurrentDirectory(), sourceFiles = <String, SourceFile>{} {
     var libraryUri = cwd.resolve(libraryRoot.toString());
     var packageUri;
     if (packageRoot != null) {
       packageUri = cwd.resolve(packageRoot.toString());
     } else {
       packageUri = libraryUri;
     }
     _compiler = new api.Compiler(provider, handler,
-        libraryUri, packageUri, <String>[]);
+        libraryUri, packageUri, opts);
     var scriptUri = cwd.resolve(script.toString());
     // TODO(johnniwinther): Detect file not found
     _compiler.run(scriptUri);
   }
 
   Dart2JsCompilation.library(List<Path> libraries, Path libraryRoot,
                      [Path packageRoot, List<String> opts = const <String>[]])
       : cwd = getCurrentDirectory(), sourceFiles = <String, SourceFile>{} {
     var libraryUri = cwd.resolve(libraryRoot.toString());
     var packageUri;
     if (packageRoot != null) {
       packageUri = cwd.resolve(packageRoot.toString());
     } else {
       packageUri = libraryUri;
     }
     _compiler = new LibraryCompiler(provider, handler,
-        libraryUri, packageUri, <String>[]);
+        libraryUri, packageUri, opts);
     var librariesUri = <Uri>[];
     for (Path library in libraries) {
       librariesUri.add(cwd.resolve(library.toString()));
       // TODO(johnniwinther): Detect file not found
     }
     LibraryCompiler libraryCompiler = _compiler;
     libraryCompiler.runList(librariesUri);
   }
 
   MirrorSystem get mirrors => new Dart2JsMirrorSystem(_compiler);
@@ skipping 105 matching lines @@
     }
     return node.getBeginToken();
   }
 
   Script getScript() => _element.getCompilationUnit().script;
 
   String toString() => _element.toString();
 
   int get hashCode => qualifiedName.hashCode;
 
+  void _appendCommentTokens(Token commentToken) {
+    while (commentToken != null && commentToken.kind == COMMENT_TOKEN) {
+      _metadata.add(new Dart2JsCommentInstanceMirror(
+          mirrors, commentToken.slowToString()));
+      commentToken = commentToken.next;
+    }
+  }
+
   List<InstanceMirror> get metadata {
     if (_metadata == null) {
       _metadata = <InstanceMirror>[];
       for (MetadataAnnotation metadata in _element.metadata) {
+        _appendCommentTokens(mirrors.compiler.commentMap[metadata.beginToken]);

[ahe, 2013/01/03 13:04:09]

I think this has horrible performance.

         metadata.ensureResolved(mirrors.compiler);
         _metadata.add(
             _convertConstantToInstanceMirror(mirrors, metadata.value));
       }
+      _appendCommentTokens(mirrors.compiler.commentMap[getBeginToken()]);

[ahe, 2013/01/03 13:04:09]

Ditto.

     }
     // TODO(johnniwinther): Return an unmodifiable list instead.
     return new List<InstanceMirror>.from(_metadata);
   }
 }
 
 //------------------------------------------------------------------------------
 // Mirror system implementation.
 //------------------------------------------------------------------------------
 
@@ skipping 1214 matching lines @@
 
   Future<InstanceMirror> getField(String fieldName) {
     _ensureFieldMap();
     Constant fieldConstant = _fieldMap[fieldName];
     if (fieldConstant != null) {
       return new Future<InstanceMirror>.immediate(
           _convertConstantToInstanceMirror(mirrors, fieldConstant));
     }
     return super.getField(fieldName);
   }
+}
+
+
+/**
+ * Pulls the raw text out of a doc comment (i.e. removes the comment
+ * characters).
+ */
+String _stripComment(String comment) {

[Andrei Mouravski, 2013/01/02 16:56:06]

Why not make this public or even put it into a utils library somewhere? It seems
like something that can be useful elsewhere.

+  if (comment.startsWith('///')) {
+    var line = comment.substring(3);
+    // Allow a leading space.

[ahe, 2013/01/03 13:04:09]

allow -> strip.

+    if (line.startsWith(' ')) line = line.substring(1);
+    return line;
+  } else {

[ahe, 2013/01/03 13:04:09]

I suggest you handle this case differently, per my comments below.

First, remove leading r'/\*\* ?' from comment.
Then, remove trailing r' ?\*/' from comment.
Now split the lines.  Add the first line to buf.
Remove trailing r'[ \t]*\* ?' of the remaining lines (not the first) and add
them to buf. For example:

for (var line in comment.split('\n')) {
  if (buf.isEmpty) {
    buf.add(line); // Add the first line unprocessed.
    continue;
  }
  buf.add('\n');
  Match match = new RegExp(r'^[ \t]*\* ?(.*)').firstMatch(line);
  if (match != null) line = match[1];
  buf.add(line);
}

+    StringBuffer buf = new StringBuffer();
+    for (var line in comment.split('\n')) {
+      line = line.trim();

[ahe, 2013/01/03 13:04:09]

This deletes trailing whitespace, unlike how you handle ///.

+      if (line.startsWith('/**')) line = line.substring(3);

[ahe, 2013/01/03 13:04:09]

You don't need to trim the line to test for this.

+      if (line.endsWith('*/')) line = line.substring(0, line.length - 2);

[ahe, 2013/01/03 13:04:09]

You don't need to trim the line to test for this.

+      line = line.trim();

[ahe, 2013/01/03 13:04:09]

I don't understand why you're trimming again.

+      if (line.startsWith('* ')) {

[ahe, 2013/01/03 13:04:09]

This has weird behavior for comments like this:

/** *Important:* Don't remove too much! */

+        line = line.substring(2);
+      } else if (line.startsWith('*')) {
+        line = line.substring(1);
+      }
+
+      buf.add(line);
+      buf.add('\n');
+    }
+    return buf.toString();
+  }
+}
+
+class Dart2JsCommentInstanceMirror implements CommentInstanceMirror {
+  final Dart2JsMirrorSystem mirrors;
+  final String text;
+  String _trimmedText;
+
+  Dart2JsCommentInstanceMirror(this.mirrors, this.text);
+
+  ClassMirror get type {
+    var uri = new Uri.fromComponents(scheme: 'dart', path: 'mirrors');
+    LibraryElement libraryElement =
+        mirrors.compiler.libraryLoader.loadLibrary(uri, null, uri);

[ahe, 2013/01/03 13:04:09]

This seems overly lazy. Can you initialize the object with this information
instead?

[Johnni Winther, 2013/01/04 16:40:53]

The class element is now loaded in [Compiler.scanBuiltinLibraries] if
[Compiler.preserveComments] is true.

+    var element = libraryElement.find(const SourceString('Comment'));
+    return new Dart2JsClassMirror(mirrors, element);
+  }
+
+  bool get isDocComment => text.startsWith('/**') || text.startsWith('///');
+
+  String get trimmedText {
+    if (_trimmedText == null) {
+      _trimmedText = _stripComment(text);
+    }
+    return _trimmedText;
+  }
+
+  bool get hasReflectee => false;
+
+  get reflectee {
+    // TODO(johnniwinther): Which exception/error should be thrown here?
+    throw new UnsupportedError('InstanceMirror does not have a reflectee');
+  }
+
+  Future<InstanceMirror> getField(String fieldName) {
+    if (fieldName == 'isDocComment') {
+      return new Future.immediate(
+          new Dart2JsBoolConstantMirror(mirrors,
+               isDocComment ? new TrueConstant() : new FalseConstant()));
+    } else if (fieldName == 'text') {
+      return new Future.immediate(
+          new Dart2JsStringConstantMirror(mirrors,
+              new StringConstant(new DartString.literal(text), null)));
+    } else if (fieldName == 'trimmedText') {
+      return new Future.immediate(
+          new Dart2JsStringConstantMirror(mirrors,
+              new StringConstant(new DartString.literal(trimmedText), null)));

[ahe, 2013/01/03 13:04:09]

You might benefit from a new constructor on Dart2JsStringConstantMirror that
just takes a String.

[Johnni Winther, 2013/01/04 16:40:53]

Done.

+    }
+    // TODO(johnniwinther): Which exception/error should be thrown here?
+    throw new UnsupportedError('InstanceMirror does not have a reflectee');
+  }
 }