Added generic information for return types.

pkg/docgen/lib/docgen.dart

Index: pkg/docgen/lib/docgen.dart
diff --git a/pkg/docgen/lib/docgen.dart b/pkg/docgen/lib/docgen.dart
index 72f6a132bf9d8c2a7f2d0651c9822b3559fdd586..f49c313e2129df914512950fba7e66faf6767cbb 100644
--- a/pkg/docgen/lib/docgen.dart
+++ b/pkg/docgen/lib/docgen.dart
@@ -168,10 +168,6 @@ Future<MirrorSystem> getMirrorSystem(List<String> args, {String packageRoot,
   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.
@@ -330,7 +326,7 @@ Map<String, Map<String, Method>> _getMethods
   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;
@@ -430,6 +426,28 @@ Map<String, Generic> _getGenerics(ClassMirror mirror) {
 }
 
 /**
+ * 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) {
@@ -512,7 +530,6 @@ class Library extends Indexable {
 /**
  * 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.
@@ -617,13 +634,13 @@ class Method extends Indexable {
   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);
   
@@ -635,7 +652,7 @@ class Method extends Indexable {
       '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)
     };
@@ -684,4 +701,35 @@ class Generic {
       '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()))
+    };
 }