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';
 
 import 'mirrors.dart';
+import 'mirrors_util.dart';
 import 'util.dart';
 
 //------------------------------------------------------------------------------
 // Utility types and functions for the dart2js mirror system
 //------------------------------------------------------------------------------
 
 bool _isPrivate(String name) {
   return name.startsWith('_');
 }
 
@@ skipping 348 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 12 matching lines @@
 }
 
 abstract class Dart2JsDeclarationMirror extends Dart2JsMirror
     implements DeclarationMirror {
 
   bool get isTopLevel => owner != null && owner is LibraryMirror;
 
   bool get isPrivate => _isPrivate(simpleName);
 
   /**
-   * Returns the first token for the source of this declaration.
+   * Returns the first token for the source of this declaration, not including
+   * metadata annotations.
    */
   Token getBeginToken();
 
   /**
    * Returns the last token for the source of this declaration.
    */
   Token getEndToken();
 
   /**
    * Returns the script for the source of this declaration.
    */
   Script getScript();
-
-  SourceLocation get location {
-    Token beginToken = getBeginToken();
-    Script script = getScript();
-    SourceSpan span;
-    if (beginToken == null) {
-      span = new SourceSpan(script.uri, 0, 0);
-    } else {
-      Token endToken = getEndToken();
-      span = mirrors.compiler.spanFromTokens(beginToken, endToken, script.uri);
-    }
-    return new Dart2JsSourceLocation(script, span);
-  }
 }
 
 abstract class Dart2JsMemberMirror extends Dart2JsElementMirror
     implements MemberMirror {
 
   Dart2JsMemberMirror(Dart2JsMirrorSystem system, Element element)
       : super(system, element);
 
   bool get isConstructor => false;
 
   bool get isVariable => false;
 
   bool get isMethod => false;
 
   bool get isStatic => false;
 
   bool get isParameter => false;
 }
 
 abstract class Dart2JsTypeMirror extends Dart2JsDeclarationMirror

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

This class defines no behavior, so it has no purpose.

Chances are that you have code somewhere that says:

if (m is Dart2JsTypeMirror) doSomething(x);

Generally, I'd prefer:

m.doSomething();

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

It is an 'interface' extending both Dart2JsDeclarationMirror and TypeMirror, and
as such defines their combined behavior.

     implements TypeMirror {
 

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

Extra line.

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

Done.

 }
 
 abstract class Dart2JsElementMirror extends Dart2JsDeclarationMirror {

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

Generally, I prefer having the super class first. Makes the code easier to read.

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

Done.

   final Dart2JsMirrorSystem mirrors;
   final Element _element;
   List<InstanceMirror> _metadata;
 
   Dart2JsElementMirror(this.mirrors, this._element) {
     assert (mirrors != null);
     assert (_element != null);
   }
 
   String get simpleName => _element.name.slowToString();
 
   String get displayName => simpleName;
 
   /**
-   * Computes the first token for this declaration using the first metadata
-   * annotation, the begin token of the element node or element position as
-   * indicator.
+   * Computes the first token for this declaration using the begin token of the
+   * element node or element position as indicator.
    */
   Token getBeginToken() {
-    if (!_element.metadata.isEmpty) {
-      for (MetadataAnnotation metadata in _element.metadata) {
-        if (metadata.beginToken != null) {
-          return metadata.beginToken;
-        }
-      }
-    }
     // TODO(johnniwinther): Avoid calling [parseNode].
     Node node = _element.parseNode(mirrors.compiler);
     if (node == null) {
       return _element.position();
     }
     return node.getBeginToken();
   }
 
   /**
    * Computes the last token for this declaration using the end token of the
    * element node or element position as indicator.
    */
   Token getEndToken() {
     // TODO(johnniwinther): Avoid calling [parseNode].
     Node node = _element.parseNode(mirrors.compiler);
     if (node == null) {
       return _element.position();
     }
     return node.getEndToken();
   }
 
+  /**
+   * Returns the first token for the source of this declaration, including
+   * metadata annotations.
+   */
+  Token getFirstToken() {
+    if (!_element.metadata.isEmpty) {
+      for (MetadataAnnotation metadata in _element.metadata) {
+        if (metadata.beginToken != null) {
+          return metadata.beginToken;
+        }
+      }
+    }
+    return getBeginToken();
+  }
+
   Script getScript() => _element.getCompilationUnit().script;
 
+  SourceLocation get location {
+    Token beginToken = getFirstToken();
+    Script script = getScript();
+    SourceSpan span;
+    if (beginToken == null) {
+      span = new SourceSpan(script.uri, 0, 0);
+    } else {
+      Token endToken = getEndToken();
+      span = mirrors.compiler.spanFromTokens(beginToken, endToken, script.uri);
+    }
+    return new Dart2JsSourceLocation(script, span);
+  }
+
   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]);
         metadata.ensureResolved(mirrors.compiler);
         _metadata.add(
             _convertConstantToInstanceMirror(mirrors, metadata.value));
       }
+      _appendCommentTokens(mirrors.compiler.commentMap[getBeginToken()]);
     }
     // TODO(johnniwinther): Return an unmodifiable list instead.
     return new List<InstanceMirror>.from(_metadata);
   }
 }
 
 //------------------------------------------------------------------------------
 // Mirror system implementation.
 //------------------------------------------------------------------------------
 
@@ skipping 157 matching lines @@
       });
     }
   }
 
   Map<String, ClassMirror> get classes {
     _ensureClasses();
     return new ImmutableMapWrapper<String, ClassMirror>(_classes);
   }
 
   /**
-   * Computes the first token of this library using the first metadata
-   * annotation or the first library tag as indicator.
+   * Computes the first token of this library using the first library tag as
+   * indicator.
    */
   Token getBeginToken() {
-    if (!_element.metadata.isEmpty) {
-      for (MetadataAnnotation metadata in _element.metadata) {
-        if (metadata.beginToken != null) {
-          return metadata.beginToken;
-        }
-      }
-    }
     if (_library.libraryTag != null) {
       return _library.libraryTag.getBeginToken();
     } else if (!_library.tags.isEmpty) {
       return _library.tags.reverse().head.getBeginToken();
     }
     return null;
   }
 
   /**
    * Computes the first token of this library using the last library tag as
@@ skipping 908 matching lines @@
 
   bool get hasReflectee => true;
 
   get reflectee => null;
 }
 
 class Dart2JsBoolConstantMirror extends Dart2JsConstantMirror {
   Dart2JsBoolConstantMirror(Dart2JsMirrorSystem mirrors, BoolConstant constant)
       : super(mirrors, constant);
 
+  Dart2JsBoolConstantMirror.fromBool(Dart2JsMirrorSystem mirrors, bool value)
+      : super(mirrors, value ? new TrueConstant() : new FalseConstant());
+
   BoolConstant get _constant => super._constant;
 
   bool get hasReflectee => true;
 
   get reflectee => _constant is TrueConstant;
 }
 
 class Dart2JsStringConstantMirror extends Dart2JsConstantMirror {
   Dart2JsStringConstantMirror(Dart2JsMirrorSystem mirrors,
                               StringConstant constant)
       : super(mirrors, constant);
 
+  Dart2JsStringConstantMirror.fromString(Dart2JsMirrorSystem mirrors,
+                                         String text)
+      : super(mirrors,
+              new StringConstant(new DartString.literal(text), null));
+
   StringConstant get _constant => super._constant;
 
   bool get hasReflectee => true;
 
   get reflectee => _constant.value.slowToString();
 }
 
 class Dart2JsNumConstantMirror extends Dart2JsConstantMirror {
   Dart2JsNumConstantMirror(Dart2JsMirrorSystem mirrors,
                            NumConstant constant)
@@ skipping 100 matching lines @@
   }
 
   Future<InstanceMirror> getField(String fieldName) {
     Constant fieldConstant = _fieldMap[fieldName];
     if (fieldConstant != null) {
       return new Future<InstanceMirror>.immediate(
           _convertConstantToInstanceMirror(mirrors, fieldConstant));
     }
     return super.getField(fieldName);
   }
+}
+
+class Dart2JsCommentInstanceMirror implements CommentInstanceMirror {
+  final Dart2JsMirrorSystem mirrors;
+  final String text;
+  String _trimmedText;
+
+  Dart2JsCommentInstanceMirror(this.mirrors, this.text);
+
+  ClassMirror get type {
+    return new Dart2JsClassMirror(mirrors, mirrors.compiler.documentClass);
+  }
+
+  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.fromBool(mirrors, isDocComment));
+    } else if (fieldName == 'text') {
+      return new Future.immediate(
+          new Dart2JsStringConstantMirror.fromString(mirrors, text));
+    } else if (fieldName == 'trimmedText') {
+      return new Future.immediate(
+          new Dart2JsStringConstantMirror.fromString(mirrors, trimmedText));
+    }
+    // TODO(johnniwinther): Which exception/error should be thrown here?
+    throw new UnsupportedError('InstanceMirror does not have a reflectee');
+  }
 }