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 138 matching lines @@
 
   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, _getReturnType(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 79 matching lines @@
 /**
  * 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 [ReturnType] object constructed from the Method.returnType 
+ * Type mirror. 
+ */

[Alan Knight, 2013/07/24 23:06:44]

I don't love these names. "get" is usually not providing any more information,
and "helper" likewise. What about just calling it _returnType(TypeMirror mirror)
and _typeParameters(TypeMirror mirror)?

Although that also makes me wonder why any of this is specific to return types.
Don't these apply to all types?

[janicejl, 2013/07/25 00:29:37]

Done. That was a good point, it was not specific to only return types. Thanks. 

Have added for variables and parameters instead of only method return types. 

+ReturnType _getReturnType(TypeMirror mirror) {
+  return new ReturnType(mirror.qualifiedName, _getReturnTypeHelper(mirror));
+}
+
+/**
+ * Returns a list of [ReturnType] objects constructed from TypeMirrors. 
+ */
+List<ReturnType> _getReturnTypeHelper(TypeMirror mirror) {
+  if (mirror is ClassMirror) {
+    var innerList = [];
+    mirror.typeArguments.forEach((e) {
+      innerList.add(new ReturnType(e.qualifiedName, _getReturnTypeHelper(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 84 matching lines @@
  * 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;
-
+  ReturnType 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 {
 
@@ skipping 28 matching lines @@
 class Generic {
   String name;
   String type;
   
   Generic(this.name, this.type);
   
   Map toMap() => {
       'name': name,
       'type': type
     };
+}
+
+/**
+ * A class containing properties of a return type. 

[Alan Knight, 2013/07/24 23:06:44]

We know it's a class, what does "containing properties" mean? Something like
"Holds the name of a return type, and its generic type parameters" would be more
concrete.

[janicejl, 2013/07/25 00:29:37]

Done.

+ * 
+ * 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" :
+ */
+class ReturnType {
+  String outer;
+  List<ReturnType> inner;
+  
+  ReturnType(this.outer, this.inner);
+  
+  Map toMap() => {
+      'outer': outer,
+      'inner': new List.from(inner.map((e) => e.toMap()))
+    };
 }