annotation with parameters.

pkg/docgen/lib/docgen.dart

 // Copyright (c) 2013, 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.
 
 /**
  * **docgen** is a tool for creating machine readable representations of Dart
  * code metadata, including: classes, members, comments and annotations.
  *
  * docgen is run on a `.dart` file or a directory containing `.dart` files.
  *
@@ skipping 220 matching lines @@
   // results. 
   _writeToFile(filteredEntities.map((e) => e.qualifiedName).join('\n'), 
       'index.txt', append: append);
 }
 
 Library generateLibrary(dart2js.Dart2JsLibraryMirror library) {
   _currentLibrary = library;
   var result = new Library(library.qualifiedName, _commentToHtml(library),
       _variables(library.variables),
       _methods(library.functions),
-      _classes(library.classes), _isPrivate(library));
+      _classes(library.classes), _isHidden(library));
   logger.fine('Generated library for ${result.name}');
   return result;
 }
 
 void _writeIndexableToFile(Indexable result, bool outputToYaml) {
   if (outputToYaml) {
     _writeToFile(getYamlString(result.toMap()), '${result.qualifiedName}.yaml');
   } else {
     _writeToFile(stringify(result.toMap()), '${result.qualifiedName}.json');
   }
@@ skipping 10 matching lines @@
 bool _isLibraryPrivate(LibraryMirror mirror) {
   if (mirror.simpleName.startsWith('_') || mirror.simpleName.contains('._')) {
     return true;
   }
   return false;
 }
 
 /**
  * A declaration is private if itself is private, or the owner is private. 
  */
-bool _isPrivate(DeclarationMirror mirror) {
+// Issue(12202) - A declaration is public even if it's owner is private. 
+bool _isHidden(DeclarationMirror mirror) {
   if (mirror is LibraryMirror) {
     return _isLibraryPrivate(mirror);
   } else if (mirror.owner is LibraryMirror) {
     return (mirror.isPrivate || _isLibraryPrivate(mirror.owner));
   } else { 
-    return (mirror.isPrivate || _isPrivate(mirror.owner));
+    return (mirror.isPrivate || _isHidden(mirror.owner));
   }
 }
 
 bool _isVisible(Indexable item) {
   return _includePrivate || !item.isPrivate;
 }
 
 /**
  * Returns a list of meta annotations assocated with a mirror.
  */
 List<String> _annotations(DeclarationMirror mirror) {
-  var annotations = mirror.metadata.where((e) =>
+  var annotationMirrors = mirror.metadata.where((e) =>
       e is dart2js.Dart2JsConstructedConstantMirror);
-  return annotations.map((e) => e.type.qualifiedName).toList();
+  var annotations = [];
+  annotationMirrors.forEach((annotation) {
+    var parameterList = annotation.type.variables.values
+      .where((e) => e.isFinal)
+      .map((e) => annotation.getField(e.simpleName).reflectee)
+      .where((e) => e != null)
+      .toList();
+    annotations.add(new Annotation(annotation.type.qualifiedName,
+        parameterList));
+  });
+  return annotations;
 }
 
 /**
  * Returns any documentation comments associated with a mirror with
  * simple markdown converted to html.
  */
 String _commentToHtml(DeclarationMirror mirror) {
   String commentText;
   mirror.metadata.forEach((metadata) {
     if (metadata is CommentInstanceMirror) {
@@ skipping 32 matching lines @@
 
 /**
  * Returns a map of [Variable] objects constructed from [mirrorMap].
  */
 Map<String, Variable> _variables(Map<String, VariableMirror> mirrorMap) {
   var data = {};
   // TODO(janicejl): When map to map feature is created, replace the below with
   // a filter. Issue(#9590).
   mirrorMap.forEach((String mirrorName, VariableMirror mirror) {
     _currentMember = mirror;
-    if (_includePrivate || !_isPrivate(mirror)) {
+    if (_includePrivate || !_isHidden(mirror)) {
       entityMap[mirror.qualifiedName] = new Variable(mirrorName, mirror.isFinal,
          mirror.isStatic, mirror.isConst, _type(mirror.type),
          _commentToHtml(mirror), _annotations(mirror), mirror.qualifiedName,
-         _isPrivate(mirror), mirror.owner.qualifiedName);
+         _isHidden(mirror), mirror.owner.qualifiedName);
       data[mirrorName] = entityMap[mirror.qualifiedName];
     }
   });
   return data;
 }
 
 /**
  * Returns a map of [Method] objects constructed from [mirrorMap].
  */
 MethodGroup _methods(Map<String, MethodMirror> mirrorMap) {
   var group = new MethodGroup();
   mirrorMap.forEach((String mirrorName, MethodMirror mirror) {
-    if (_includePrivate || !_isPrivate(mirror)) {
+    if (_includePrivate || !_isHidden(mirror)) {
       group.addMethod(mirror);
     }
   });
   return group;
 } 
 
 /**
  * Returns the [Class] for the given [mirror] has already been created, and if 
  * it does not exist, creates it.
  */
 Class _class(ClassMirror mirror) {
   var clazz = entityMap[mirror.qualifiedName];
   if (clazz == null) {
     var superclass = mirror.superclass != null ? 
         _class(mirror.superclass) : null;
     var interfaces = 
         mirror.superinterfaces.map((interface) => _class(interface));
     clazz = new Class(mirror.simpleName, superclass, _commentToHtml(mirror), 
         interfaces.toList(), _variables(mirror.variables),
         _methods(mirror.methods), _annotations(mirror), _generics(mirror), 
-        mirror.qualifiedName, _isPrivate(mirror), mirror.owner.qualifiedName);
+        mirror.qualifiedName, _isHidden(mirror), mirror.owner.qualifiedName);
     entityMap[mirror.qualifiedName] = clazz;
   }
   return clazz;
 }
 
 /**
  * Returns a map of [Class] objects constructed from [mirrorMap].
  */
 ClassGroup _classes(Map<String, ClassMirror> mirrorMap) {
   var group = new ClassGroup();
@@ skipping 235 matching lines @@
     if (_isVisible(superclass)) return superclass.qualifiedName;
     return superclass.validSuperclass();
   }
   
   /// Generates a map describing the [Class] object.
   Map toMap() => {
     'name': name,
     'qualifiedname': qualifiedName,
     'comment': comment,
     'superclass': validSuperclass(),
-    'implements': new List.from(interfaces.where(_isVisible)
-        .map((e) => e.qualifiedName)),
-    'subclass': new List.from(subclasses),
+    'implements': interfaces.where(_isVisible)
+        .map((e) => e.qualifiedName).toList(),
+    'subclass': subclasses,
     'variables': recurseMap(variables),
     'inheritedvariables': recurseMap(inheritedVariables),
     'methods': methods.toMap(),
     'inheritedmethods': inheritedMethods.toMap(),
-    'annotations': new List.from(annotations),
+    'annotations': annotations.map((a) => a.toMap()).toList(),
     'generics': recurseMap(generics)
   };
 }
 
 /**
  * A container to categorize classes into the following groups: abstract 
  * classes, regular classes, typedefs, and errors. 
  */
 class ClassGroup {
   Map<String, Class> abstractClasses = {};
@@ skipping 13 matching lines @@
       clazz.addInherited(parent);
     });
     
     if (isError(mirror.qualifiedName)) {
       errors[mirror.simpleName] = clazz;
     } else if (mirror.isTypedef) {
       if (_includePrivate || !mirror.isPrivate) {
         entityMap[mirror.qualifiedName] = new Typedef(mirror.simpleName, 
             mirror.value.returnType.qualifiedName, _commentToHtml(mirror), 
             _generics(mirror), _parameters(mirror.value.parameters),
-            _annotations(mirror), mirror.qualifiedName,  _isPrivate(mirror), 
+            _annotations(mirror), mirror.qualifiedName,  _isHidden(mirror), 
             mirror.owner.qualifiedName);
         typedefs[mirror.simpleName] = entityMap[mirror.qualifiedName];
       }
     } else if (mirror.isAbstract) {
       abstractClasses[mirror.simpleName] = clazz;
     } else if (mirror.isClass) {
       regularClasses[mirror.simpleName] = clazz;
     } else {
       throw new ArgumentError('${mirror.simpleName} - no class type match. ');
     }
   }
   
   /**
    * Checks if the given name is a key for any of the Class Maps. 
    */
   bool containsKey(String name) {
     return abstractClasses.containsKey(name) ||
         regularClasses.containsKey(name) ||
         errors.containsKey(name);
   }
   
   Map toMap() => {
-    'abstract': new List.from(abstractClasses.values
-        .where(_isVisible).map((e) => e.qualifiedName)),
-    'class': new List.from(regularClasses.values
-        .where(_isVisible).map((e) => e.qualifiedName)),
+    'abstract': abstractClasses.values.where(_isVisible)
+      .map((e) => e.qualifiedName).toList(),
+    'class': regularClasses.values.where(_isVisible)
+      .map((e) => e.qualifiedName).toList(),
     'typedef': recurseMap(typedefs),
-    'error': new List.from(errors.values
-        .where(_isVisible).map((e) => e.qualifiedName))
+    'error': errors.values.where(_isVisible)
+      .map((e) => e.qualifiedName).toList()
   };
 }
 
 class Typedef extends Indexable {
   String returnType;
   
   Map<String, Parameter> parameters;
   
   /// Generic information about the typedef. 
   Map<String, Generic> generics;
   
   /// List of the meta annotations on the typedef. 
   List<String> annotations;
   
   Typedef(String name, this.returnType, String comment, this.generics, 
       this.parameters, this.annotations,
       String qualifiedName, bool isPrivate, String owner) : super(name, comment,
           qualifiedName, isPrivate, owner) {}
   
   Map toMap() => {
     'name': name,
     'qualifiedname': qualifiedName,
     'comment': comment,
     'return': returnType,
     'parameters': recurseMap(parameters),
-    'annotations': new List.from(annotations),
+    'annotations': annotations.map((a) => a.toMap()).toList(),
     'generics': recurseMap(generics)
   };
 }
 
 /**
  * A class containing properties of a Dart variable.
  */
 class Variable extends Indexable {
 
   bool isFinal;
@@ skipping 10 matching lines @@
   
   /// Generates a map describing the [Variable] object.
   Map toMap() => {
     'name': name,
     'qualifiedname': qualifiedName,
     'comment': comment,
     'final': isFinal.toString(),
     'static': isStatic.toString(),
     'constant': isConst.toString(),
     'type': new List.filled(1, type.toMap()),
-    'annotations': new List.from(annotations)
+    'annotations': annotations.map((a) => a.toMap()).toList()
   };
 }
 
 /**
  * A class containing properties of a Dart method.
  */
 class Method extends Indexable {
 
   /// Parameters for this method.
   Map<String, Parameter> parameters;
@@ skipping 14 matching lines @@
   /// Generates a map describing the [Method] object.
   Map toMap() => {
     'name': name,
     'qualifiedname': qualifiedName,
     'comment': comment,
     'static': isStatic.toString(),
     'abstract': isAbstract.toString(),
     'constant': isConst.toString(),
     'return': new List.filled(1, returnType.toMap()),
     'parameters': recurseMap(parameters),
-    'annotations': new List.from(annotations)
+    'annotations': annotations.map((a) => a.toMap()).toList()
   };
 }
 
 /**
  * A container to categorize methods into the following groups: setters, 
  * getters, constructors, operators, regular methods. 
  */
 class MethodGroup {
   Map<String, Method> setters = {};
   Map<String, Method> getters = {};
   Map<String, Method> constructors = {};
   Map<String, Method> operators = {};
   Map<String, Method> regularMethods = {};
   
   void addMethod(MethodMirror mirror) {
     var method = new Method(mirror.simpleName, mirror.isStatic, 
         mirror.isAbstract, mirror.isConstConstructor, _type(mirror.returnType), 
         _commentToHtml(mirror), _parameters(mirror.parameters), 
-        _annotations(mirror), mirror.qualifiedName, _isPrivate(mirror),
+        _annotations(mirror), mirror.qualifiedName, _isHidden(mirror),
         mirror.owner.qualifiedName);
     entityMap[mirror.qualifiedName] = method;
     _currentMember = mirror;
     if (mirror.isSetter) {
       setters[mirror.simpleName] = method;
     } else if (mirror.isGetter) {
       getters[mirror.simpleName] = method;
     } else if (mirror.isConstructor) {
       constructors[mirror.simpleName] = method;
     } else if (mirror.isOperator) {
@@ skipping 46 matching lines @@
       this.type, this.defaultValue, this.annotations);
   
   /// Generates a map describing the [Parameter] object.
   Map toMap() => {
     'name': name,
     'optional': isOptional.toString(),
     'named': isNamed.toString(),
     'default': hasDefaultValue.toString(),
     'type': new List.filled(1, type.toMap()),
     'value': defaultValue,
-    'annotations': new List.from(annotations)
+    'annotations': annotations.map((a) => a.toMap()).toList()
   };
 }
 
 /**
  * A class containing properties of a Generic. 
  */
 class Generic {
   String name;
   String type;
   
@@ skipping 36 matching lines @@
  *                      "inner" :
  */
 class Type {
   String outer;
   List<Type> inner;
   
   Type(this.outer, this.inner);
   
   Map toMap() => {
     'outer': outer,
-    'inner': new List.from(inner.map((e) => e.toMap()))
+    'inner': inner.map((e) => e.toMap()).toList()
+  };
+}
+
+/**
+ * Holds the name of the annotation, and its parameters. 
+ */
+class Annotation {
+  String qualifiedName;
+  List<String> parameters; 
+  
+  Annotation(this.qualifiedName, this.parameters);
+  
+  Map toMap() => {
+    'name': qualifiedName,
+    'parameters': parameters
   };
 }