Added generic information for return types.

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 150 matching lines @@
   } else {
     // If DART_SDK is not defined in the environment,
     // assuming the dart executable is from the Dart SDK folder inside bin.
     sdkRoot = path.join(path.dirname(path.dirname(path.dirname(path.dirname(
         path.absolute(new Options().script))))), 'sdk');
     logger.info('SDK Root: ${sdkRoot}');
   }
   return _analyzeLibraries(libraries, sdkRoot, packageRoot: packageRoot);
 }
 
-// TODO(janicejl): Should make docgen fail gracefully, or output a friendly
-// error message letting them know why it is failing to create a mirror system.
-// If there is conflicting library names, should modify it with a hash at the
-// end of it's library name.
 /**
  * Analyzes set of libraries and provides a mirror system which can be used
  * for static inspection of the source code.
  */
 Future<MirrorSystem> _analyzeLibraries(List<String> libraries,
       String libraryRoot, {String packageRoot}) {
   SourceFileProvider provider = new SourceFileProvider();
   api.DiagnosticHandler diagnosticHandler =
         new FormattingDiagnosticHandler(provider).diagnosticHandler;
   Uri libraryUri = new Uri(scheme: 'file', path: appendSlash(libraryRoot));
@@ skipping 116 matching lines @@
  */
 Map<String, Variable> _getVariables(Map<String, VariableMirror> mirrorMap,
     bool includePrivate) {
   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) {
     if (includePrivate || !mirror.isPrivate) {
       _currentMember = mirror;
       data[mirrorName] = new Variable(mirrorName, mirror.isFinal, 
-          mirror.isStatic, mirror.isConst, mirror.type.qualifiedName,
+          mirror.isStatic, mirror.isConst, _type(mirror.type),
           _getComment(mirror), _getAnnotations(mirror), mirror.qualifiedName);
     }
   });
   return data;
 }
 
 /**
  * Returns a map of [Method] objects constructed from [mirrorMap].
  */
 Map<String, Map<String, Method>> _getMethods
     (Map<String, MethodMirror> mirrorMap, bool includePrivate) {
 
   var setters = {};
   var getters = {};
   var constructors = {};
   var operators = {};
   var methods = {};
   
   mirrorMap.forEach((String mirrorName, MethodMirror mirror) {
     if (includePrivate || !mirror.isPrivate) {
       var method = new Method(mirrorName, mirror.isStatic, mirror.isAbstract,
-          mirror.isConstConstructor, mirror.returnType.qualifiedName, 
+          mirror.isConstConstructor, _type(mirror.returnType), 
           _getComment(mirror), _getParameters(mirror.parameters), 
           _getAnnotations(mirror), mirror.qualifiedName);
       _currentMember = mirror;
       if (mirror.isSetter) {
         setters[mirrorName] = method;
       } else if (mirror.isGetter) {
         getters[mirrorName] = method;
       } else if (mirror.isConstructor) {
         constructors[mirrorName] = method;
       } else if (mirror.isOperator) {
@@ skipping 63 matching lines @@
 
 /**
  * Returns a map of [Parameter] objects constructed from [mirrorList].
  */
 Map<String, Parameter> _getParameters(List<ParameterMirror> mirrorList) {
   var data = {};
   mirrorList.forEach((ParameterMirror mirror) {
     _currentMember = mirror;
     data[mirror.simpleName] = new Parameter(mirror.simpleName, 
         mirror.isOptional, mirror.isNamed, mirror.hasDefaultValue, 
-        mirror.type.qualifiedName, mirror.defaultValue, 
+        _type(mirror.type), mirror.defaultValue, 
         _getAnnotations(mirror));
   });
   return data;
 }
 
 /**
  * Returns a map of [Generic] objects constructed from the class mirror. 
  */
 Map<String, Generic> _getGenerics(ClassMirror mirror) {
   return new Map.fromIterable(mirror.typeVariables, 
       key: (e) => e.toString(), 
       value: (e) => new Generic(e.toString(), e.upperBound.qualifiedName));
 }
 
 /**
+ * Returns a single [Type] object constructed from the Method.returnType 
+ * Type mirror. 
+ */
+Type _type(TypeMirror mirror) {
+  return new Type(mirror.qualifiedName, _typeGenerics(mirror));
+}
+
+/**
+ * Returns a list of [Type] objects constructed from TypeMirrors. 
+ */
+List<Type> _typeGenerics(TypeMirror mirror) {
+  if (mirror is ClassMirror && !mirror.isTypedef) {
+    var innerList = [];
+    mirror.typeArguments.forEach((e) {
+      innerList.add(new Type(e.qualifiedName, _typeGenerics(e)));
+    });
+    return innerList;
+  }
+  return [];
+}
+
+/**
  * Writes text to a file in the 'docs' directory.
  */
 void _writeToFile(String text, String filename) {
   Directory dir = new Directory('docs');
   if (!dir.existsSync()) {
     dir.createSync();
   }
   File file = new File('docs/$filename');
   if (!file.existsSync()) {
     file.createSync();
@@ skipping 62 matching lines @@
       'comment': comment,
       'variables': recurseMap(variables),
       'functions': recurseMap(functions),
       'classes': recurseMap(classes)
     };
 }
 
 /**
  * A class containing contents of a Dart class.
  */
-// TODO(tmandel): Figure out how to do typedefs (what is needed)
 class Class extends Indexable {
 
   /// List of the names of interfaces that this class implements.
   List<String> interfaces;
 
   /// Top-level variables in the class.
   Map<String, Variable> variables;
 
   /// Methods in the class.
   Map<String, Map<String, Method>> methods;
@@ skipping 51 matching lines @@
 }
 
 /**
  * A class containing properties of a Dart variable.
  */
 class Variable extends Indexable {
 
   bool isFinal;
   bool isStatic;
   bool isConst;
-  String type;
+  Type type;
 
   /// List of the meta annotations on the variable.
   List<String> annotations;
   
   Variable(String name, this.isFinal, this.isStatic, this.isConst, this.type, 
       String comment, this.annotations, String qualifiedName) : super(name, 
           comment, qualifiedName);
   
   /// 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': type,
+      'type': new List.filled(1, type.toMap()),
       'annotations': new List.from(annotations)
     };
 }
 
 /**
  * A class containing properties of a Dart method.
  */
 class Method extends Indexable {
 
   /// Parameters for this method.
   Map<String, Parameter> parameters;
 
   bool isStatic;
   bool isAbstract;
   bool isConst;
-  String returnType;
-
+  Type returnType;
+  
   /// List of the meta annotations on the method.
   List<String> annotations;
   
   Method(String name, this.isStatic, this.isAbstract, this.isConst, 
-      this.returnType, String comment, this.parameters, this.annotations, 
+      this.returnType, String comment, this.parameters, this.annotations,
       String qualifiedName) 
       : super(name, comment, qualifiedName);
   
   /// 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': returnType,
+      'return': new List.filled(1, returnType.toMap()),
       'parameters': recurseMap(parameters),
       'annotations': new List.from(annotations)
     };
 }
 
 /**
  * A class containing properties of a Dart method/function parameter.
  */
 class Parameter {
 
   String name;
   bool isOptional;
   bool isNamed;
   bool hasDefaultValue;
-  String type;
+  Type type;
   String defaultValue;
 
   /// List of the meta annotations on the parameter.
   List<String> annotations;
   
   Parameter(this.name, this.isOptional, this.isNamed, this.hasDefaultValue, 
       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': type,
+      'type': new List.filled(1, type.toMap()),
       'value': defaultValue,
       'annotations': new List.from(annotations)
     };
 }
 
 /**
  * A class containing properties of a Generic. 
  */
 class Generic {
   String name;
   String type;
   
   Generic(this.name, this.type);
   
   Map toMap() => {
       'name': name,
       'type': type
     };
+}
+
+/**
+ * Holds the name of a return type, and its generic type parameters.
+ * 
+ * Return types are of a form [outer]<[inner]>.
+ * If there is no [inner] part, [inner] will be an empty list. 
+ * 
+ * For example:
+ *        int size()  
+ *          "return" : 
+ *            - "outer" : dart.core.int
+ *              "inner" :
+ * 
+ *        List<String> toList()
+ *          "return" :
+ *            - "outer" : dart.core.List
+ *              "inner" : 
+ *                - "outer" : dart.core.String
+ *                  "inner" :

[Emily Fortuna, 2013/07/25 17:38:08]

can your example show an inner part, too?

[janicejl, 2013/07/25 21:39:57]

Done.

+ */
+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()))
+    };
 }