Further fixes for including package information in docs

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 114 matching lines @@
       _documentLibraries(librariesToDocument, includeSdk: includeSdk,
           outputToYaml: outputToYaml, append: append, parseSdk: parseSdk,
           introduction: introduction);
       return true;
     });
 }
 
 /// For a [library] and its corresponding [mirror] that we believe come
 /// from a package (because it has a file
 /// URI) look for the package name and set it on [library].
-_findPackage(Library library, LibraryMirror mirror) {
+void _findPackage(Library library, LibraryMirror mirror) {
     if (mirror.uri.scheme != 'file') return;
     var filePath = mirror.uri.toFilePath();
     // We assume that we are documenting only libraries under package/lib
     var rootdir = path.dirname((path.dirname(filePath)));
     var pubspec = path.join(rootdir, 'pubspec.yaml');
     library.packageName = _packageName(pubspec);
+    // If we are the main library in a package, associate the package readme
+    // with us.
+    // TODO(alanknight): We can't really rely on all packages having a library
+    // that matches the package name. Need a better way to store this.
+    if (library.packageName == library.name) {
+      library.packageIntro = _packageIntro(rootdir);
+    }
 }
 
+String _packageIntro(packageDir) {
+  var dir = new Directory(packageDir);
+  var files = dir.listSync();
+  var readmes = files.where((FileSystemEntity each) =>
+      (each is File && each.path.substring(packageDir.length + 1, each.path.length)

[Alan Knight, 2013/10/30 18:31:33]

Done.

+          .startsWith('README'))).toList();
+  if (readmes.isEmpty) return '';
+  // If there are multiples, pick the shortest name.
+  readmes.sort((a, b) => a.length.compareTo(b.length));

[terry, 2013/10/30 18:11:31]

Nice using sort.

+  var readme = readmes.first;
+  var contents = markdown.markdownToHtml(readme
+    .readAsStringSync(), linkResolver: linkResolver,
+    inlineSyntaxes: markdownSyntaxes);
+  return contents;
+}
+
+
 List<String> _listLibraries(List<String> args) {
   var libraries = new List<String>();
   for (var arg in args) {
     var type = FileSystemEntity.typeSync(arg);
 
     if (type == FileSystemEntityType.FILE) {
       if (arg.endsWith('.dart')) {
         libraries.add(path.absolute(arg));
         logger.info('Added to libraries: ${libraries.last}');
       }
@@ skipping 114 matching lines @@
 /**
  * Creates documentation for filtered libraries.
  */
 void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false,
     bool outputToYaml: true, bool append: false, bool parseSdk: false,
     String introduction: ''}) {
   libs.forEach((lib) {
     // Files belonging to the SDK have a uri that begins with 'dart:'.
     if (includeSdk || !lib.uri.toString().startsWith('dart:')) {
       var library = generateLibrary(lib);
-      entityMap[library.qualifiedName] = library;
+      entityMap[library.name] = library;
     }
   });
   // After everything is created, do a pass through all classes to make sure no
   // intermediate classes created by mixins are included.
   entityMap.values.where((e) => e is Class).forEach((c) => c.makeValid());
   // Everything is a subclass of Object, therefore empty the list to avoid a
   // giant list of subclasses to be printed out.
-  if (parseSdk) entityMap['dart.core.Object'].subclasses.clear();
+  if (parseSdk) (entityMap['dart-core.Object'] as Class).subclasses.clear();

[terry, 2013/10/30 18:11:31]

Is there a reason we can't use the name we see in our JSON files
dart.core.Object or is this a recent change that I haven't seen yet with core.

[Alan Knight, 2013/10/30 18:31:33]

That is the name in the JSON files now, we're using it consistently everywhere.

Using dots as the separator for members when we can have dots in the library
name is ambiguous. We can't tell the difference between the library a.b and the
library a, top-level field b. The client was already doing lots of
transformations where it added - into the library name for URIs (and colons so
you could write dart:core) so I made it always consistently use dashes in the
library name and do the conversion at generation time.

 
   var filteredEntities = entityMap.values.where(_isVisible);
 
   // Outputs a JSON file with all libraries and their preview comments.
   // This will help the viewer know what libraries are available to read in.
   var libraryMap;
   if (append) {
     var docsDir = listDir('docs');
     if (!docsDir.contains('docs/library_list.json')) {
       throw new StateError('No library_list.json');
@@ skipping 39 matching lines @@
   if (append) {
     var previousIndex =
         JSON.decode(new File('docs/index.json').readAsStringSync());
     index.addAll(previousIndex);
   }
   _writeToFile(JSON.encode(index), 'index.json');
 }
 
 Library generateLibrary(dart2js.Dart2JsLibraryMirror library) {
   _currentLibrary = library;
-  var result = new Library(library.qualifiedName, _commentToHtml(library),
+  var result = new Library(docName(library), _commentToHtml(library),
       _variables(library.variables),
       _methods(library.functions),
       _classes(library.classes), _isHidden(library));
   _findPackage(result, library);
   logger.fine('Generated library for ${result.name}');
   return result;
 }
 
 void _writeIndexableToFile(Indexable result, bool outputToYaml) {
+  var outputFile = result.fileName;
+  var output;
   if (outputToYaml) {
-    _writeToFile(getYamlString(result.toMap()), '${result.qualifiedName}.yaml');
+    output = getYamlString(result.toMap());
+    outputFile = outputFile + '.yaml';
   } else {
-    _writeToFile(JSON.encode(result.toMap()), '${result.qualifiedName}.json');
+    output = JSON.encode(result.toMap());
+    outputFile = outputFile + '.json';
   }
+  _writeToFile(output, outputFile);
 }
 
 /**
  * Returns true if a library name starts with an underscore, and false
  * otherwise.
  *
  * An example that starts with _ is _js_helper.
  * An example that contains ._ is dart._collection.dev
  */
 // This is because LibraryMirror.isPrivate returns `false` all the time.
@@ skipping 32 matching lines @@
 List<Annotation> _annotations(DeclarationMirror mirror) {
   var annotationMirrors = mirror.metadata.where((e) =>
       e is dart2js.Dart2JsConstructedConstantMirror);
   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();
-    if (validAnnotations.contains(annotation.type.qualifiedName)) {
-      annotations.add(new Annotation(annotation.type.qualifiedName,
+    if (validAnnotations.contains(docName(annotation.type))) {
+      annotations.add(new Annotation(docName(annotation.type),
           parameterList));
     }
   });
   return annotations;
 }
 
 /**
  * Returns any documentation comments associated with a mirror with
  * simple markdown converted to html.
  */
@@ skipping 72 matching lines @@
 
 /**
  * Converts all [foo] references in comments to <a>libraryName.foo</a>.
  */
 markdown.Node fixReference(String name, LibraryMirror currentLibrary,
     ClassMirror currentClass, MemberMirror currentMember) {
   var reference;
   var memberScope = currentMember == null ?
       null : currentMember.lookupInScope(name);
   if (memberScope != null) {
-    reference = memberScope.qualifiedName;
+    reference = docName(memberScope);
   } else {
     var classScope = currentClass == null ?
         null : currentClass.lookupInScope(name);
     if (classScope != null) {
-      reference = classScope.qualifiedName;
+      reference = docName(classScope);
     } else {
       var libraryScope = currentLibrary == null ?
           null : currentLibrary.lookupInScope(name);
-      reference = libraryScope != null ? libraryScope.qualifiedName : name;
+      reference = libraryScope != null ? docName(libraryScope) : name;
     }
   }
   return new markdown.Element.text('a', reference);
 }
 
 /**
  * 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 || !_isHidden(mirror)) {
-      entityMap[mirror.qualifiedName] = new Variable(mirrorName, mirror.isFinal,
+      entityMap[docName(mirror)] = new Variable(mirrorName, mirror.isFinal,
          mirror.isStatic, mirror.isConst, _type(mirror.type),
-         _commentToHtml(mirror), _annotations(mirror), mirror.qualifiedName,
-         _isHidden(mirror), mirror.owner.qualifiedName);
-      data[mirrorName] = entityMap[mirror.qualifiedName];
+         _commentToHtml(mirror), _annotations(mirror), docName(mirror),
+         _isHidden(mirror), docName(mirror.owner));
+      data[mirrorName] = entityMap[docName(mirror)];
     }
   });
   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 || !mirror.isPrivate) {
       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];
+  var clazz = entityMap[docName(mirror)];
   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, _isHidden(mirror), mirror.owner.qualifiedName,
+        docName(mirror), _isHidden(mirror), docName(mirror.owner),
         mirror.isAbstract);
     if (superclass != null) clazz.addInherited(superclass);
     interfaces.forEach((interface) => clazz.addInherited(interface));
-    entityMap[mirror.qualifiedName] = clazz;
+    entityMap[docName(mirror)] = clazz;
   }
   return clazz;
 }
 
 /**
  * Returns a map of [Class] objects constructed from [mirrorMap].
  */
 ClassGroup _classes(Map<String, ClassMirror> mirrorMap) {
   var group = new ClassGroup();
   mirrorMap.forEach((String mirrorName, ClassMirror mirror) {
@@ skipping 24 matching lines @@
   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));
+  return new Type(docName(mirror), _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)));
+      innerList.add(new Type(docName(e), _typeGenerics(e)));
     });
     return innerList;
   }
   return [];
 }
 
 /**
  * Writes text to a file in the 'docs' directory.
  */
 void _writeToFile(String text, String filename, {bool append: false}) {
   Directory dir = new Directory('docs');
   if (!dir.existsSync()) {
     dir.createSync();
   }
+  // We assume there's a single extra level of directory structure for packages.
+  if (path.split(filename).length > 1) {
+    var subdir = new Directory(path.join('docs', path.dirname(filename)));
+    if (!subdir.existsSync()) {
+      subdir.createSync();
+    }
+  }
+
   File file = new File('docs/$filename');
   if (!file.existsSync()) {
     file.createSync();
   }
   file.writeAsStringSync(text, mode: append ? FileMode.APPEND : FileMode.WRITE);
 }
 
 /**
  * Transforms the map by calling toMap on each value in it.
  */
 Map recurseMap(Map inputMap) {
   var outputMap = {};
   inputMap.forEach((key, value) {
     if (value is Map) {
       outputMap[key] = recurseMap(value);
     } else {
       outputMap[key] = value.toMap();
     }
   });
   return outputMap;
 }
 
 /**
  * A class representing all programming constructs, like library or class.
  */
 class Indexable {
   String name;
-  String qualifiedName;
+  String get qualifiedName => fileName;
   bool isPrivate;
 
+  // The qualified name (for URL purposes) and the file name are the same,
+  // of the form packageName/ClassName or packageName/ClassName.methodName.
+  // This defines both the URL and the directory structure.
+  String get fileName => packagePrefix + ownerPrefix + name;
+
+  Indexable get owningEntity {
+    var result = entityMap[owner];
+    return result;
+  }
+  String get ownerPrefix => owningEntity == null
+      ? (owner == null || owner.isEmpty ? '' : owner + '.')
+      : owningEntity.qualifiedName + '.';
+
+  String get packagePrefix => '';
   /// Documentation comment with converted markdown.
   String comment;
 
   /// Qualified Name of the owner of this Indexable Item.
   /// For Library, owner will be "";
   String owner;
 
-  Indexable(this.name, this.comment, this.qualifiedName, this.isPrivate,
-      this.owner);
+  Indexable(this.name, this.comment, this.isPrivate, this.owner);
 
   /// The type of this member to be used in index.txt.
   String get typeName => '';
 
   /**
    * Creates a [Map] with this [Indexable]'s name and a preview comment.
    */
   Map get previewMap {
-    var finalMap = { 'name' : qualifiedName };
+    var finalMap = { 'name' : name, 'qualifiedName' : qualifiedName };
     if (comment != '') {
       var index = comment.indexOf('</p>');
       finalMap['preview'] = '${comment.substring(0, index)}</p>';
     }
     return finalMap;
   }
+
+  String toString() => super.toString() + '(' + name.toString() + ')';

[terry, 2013/10/30 18:11:31]

String toString() => '${super.toString()}($name)'

[Alan Knight, 2013/10/30 18:31:33]

Done.

+
+  // Return a map representation of this type.
+  Map toMap() {}
 }
 
 /**
  * A class containing contents of a Dart library.
  */
 class Library extends Indexable {
 
   /// Top-level variables in the library.
   Map<String, Variable> variables;
 
   /// Top-level functions in the library.
   MethodGroup functions;
 
   /// Classes defined within the library
   ClassGroup classes;
 
   String packageName = '';
 
-  Map get previewMap => super.previewMap..['packageName'] = packageName;
+  String get packagePrefix => packageName == null || packageName.isEmpty
+      ? ''
+      : packageName + '/';

[terry, 2013/10/30 18:11:31]

'$packageName/';

[Alan Knight, 2013/10/30 18:31:33]

Done.

+
+  String packageIntro;
+
+  Map get previewMap {
+    var basic = super.previewMap;
+    basic['packageName'] = packageName;
+    if (packageIntro != null) {
+      basic['packageIntro'] = packageIntro;
+    }
+    return basic;
+  }
 
   Library(String name, String comment, this.variables,
       this.functions, this.classes, bool isPrivate) : super(name, comment,
-          name, isPrivate, "") {}
+          isPrivate, "");
 
   /// Generates a map describing the [Library] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'variables': recurseMap(variables),
     'functions': functions.toMap(),
     'classes': classes.toMap(),
     'packageName': packageName,
+    'packageIntro' : packageIntro
   };
 
   String get typeName => 'library';
 }
 
 /**
  * A class containing contents of a Dart class.
  */
 class Class extends Indexable {
 
@@ skipping 20 matching lines @@
 
   Class superclass;
   bool isAbstract;
 
   /// List of the meta annotations on the class.
   List<Annotation> annotations;
 
   Class(String name, this.superclass, String comment, this.interfaces,
       this.variables, this.methods, this.annotations, this.generics,
       String qualifiedName, bool isPrivate, String owner, this.isAbstract)
-      : super(name, comment, qualifiedName, isPrivate, owner) {
+      : super(name, comment, isPrivate, owner) {
     _mdnComment(this);
   }
 
   String get typeName => 'class';
 
   /**
    * Returns a list of all the parent classes.
    */
   List<Class> parent() {
     var parent = superclass == null ? [] : [superclass];
@@ skipping 26 matching lines @@
       });
     } else {
       subclasses.add(subclass.qualifiedName);
     }
   }
 
   /**
    * Check if this [Class] is an error or exception.
    */
   bool isError() {
-    if (qualifiedName == 'dart.core.Error' ||
-        qualifiedName == 'dart.core.Exception')
+    if (qualifiedName == 'dart-core.Error' ||
+        qualifiedName == 'dart-core.Exception')
       return true;
     for (var interface in interfaces) {
       if (interface.isError()) return true;
     }
     if (superclass == null) return false;
     return superclass.isError();
   }
 
   /**
    * Check that the class exists in the owner library.
@@ skipping 58 matching lines @@
  * classes, regular classes, typedefs, and errors.
  */
 class ClassGroup {
   Map<String, Class> classes = {};
   Map<String, Typedef> typedefs = {};
   Map<String, Class> errors = {};
 
   void addClass(ClassMirror mirror) {
     _currentClass = mirror;
     if (mirror.isTypedef) {
+      // This is actually a Dart2jsTypedefMirror, and it does define value,
+      // but we don't have visibility to that type.
+      var mirror = _currentClass;
       if (_includePrivate || !mirror.isPrivate) {
-        entityMap[mirror.qualifiedName] = new Typedef(mirror.simpleName,
-            mirror.value.returnType.qualifiedName, _commentToHtml(mirror),
+        entityMap[docName(mirror)] = new Typedef(mirror.simpleName,
+            docName(mirror.value.returnType), _commentToHtml(mirror),
             _generics(mirror), _parameters(mirror.value.parameters),
-            _annotations(mirror), mirror.qualifiedName,  _isHidden(mirror),
-            mirror.owner.qualifiedName);
-        typedefs[mirror.simpleName] = entityMap[mirror.qualifiedName];
+            _annotations(mirror), docName(mirror),  _isHidden(mirror),
+            docName(mirror.owner));
+        typedefs[mirror.simpleName] = entityMap[docName(mirror)];
       }
     } else {
       var clazz = _class(mirror);
 
       // Adding inherited parent variables and methods.
       clazz.parent().forEach((parent) {
         if (_isVisible(clazz)) {
           parent.addSubclass(clazz);
         }
       });
@@ skipping 33 matching lines @@
 
   /// Generic information about the typedef.
   Map<String, Generic> generics;
 
   /// List of the meta annotations on the typedef.
   List<Annotation> 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);
+        : super(name, comment, isPrivate, owner);
 
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'return': returnType,
     'parameters': recurseMap(parameters),
     'annotations': annotations.map((a) => a.toMap()).toList(),
     'generics': recurseMap(generics)
   };
 
   String get typeName => 'typedef';
 }
 
 /**
  * A class containing properties of a Dart variable.
  */
 class Variable extends Indexable {
 
   bool isFinal;
   bool isStatic;
   bool isConst;
   Type type;
 
   /// List of the meta annotations on the variable.
   List<Annotation> annotations;
 
   Variable(String name, this.isFinal, this.isStatic, this.isConst, this.type,
       String comment, this.annotations, String qualifiedName, bool isPrivate,
-      String owner) : super(name, comment, qualifiedName, isPrivate, owner) {
+      String owner) : super(name, comment, isPrivate, owner) {
     _mdnComment(this);
   }
 
   /// Generates a map describing the [Variable] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'final': isFinal.toString(),
     'static': isStatic.toString(),
@@ skipping 25 matching lines @@
   /// Qualified name to state where the comment is inherited from.
   String commentInheritedFrom = "";
 
   /// List of the meta annotations on the method.
   List<Annotation> annotations;
 
   Method(String name, this.isStatic, this.isAbstract, this.isConst,
       this.returnType, String comment, this.parameters, this.annotations,
       String qualifiedName, bool isPrivate, String owner, this.isConstructor,
       this.isGetter, this.isSetter, this.isOperator)
-        : super(name, comment, qualifiedName, isPrivate, owner) {
+        : super(name, comment, isPrivate, owner) {
     _mdnComment(this);
   }
 
   /**
    * Makes sure that the method with an inherited equivalent have comments.
    */
   void ensureCommentFor(Method inheritedMethod) {
     if (comment.isNotEmpty) return;
-    entityMap[inheritedMethod.owner].ensureComments();
+    (entityMap[inheritedMethod.owner] as Class).ensureComments();
     comment = inheritedMethod.comment;
     commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ?
         inheritedMethod.qualifiedName : inheritedMethod.commentInheritedFrom;
   }
 
   /// Generates a map describing the [Method] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
@@ skipping 19 matching lines @@
   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, _isHidden(mirror),
-        mirror.owner.qualifiedName, mirror.isConstructor, mirror.isGetter,
+        _annotations(mirror), docName(mirror), _isHidden(mirror),
+        docName(mirror.owner), mirror.isConstructor, mirror.isGetter,
         mirror.isSetter, mirror.isOperator);
-    entityMap[mirror.qualifiedName] = method;
+    entityMap[docName(mirror)] = 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) {
       operators[mirror.simpleName] = method;
     } else if (mirror.isRegularMethod) {
@@ skipping 87 matching lines @@
 
 /**
  * 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"
+ *            - "outer" : "dart-core.int"
  *              "inner" :
  *
  *        List<String> toList()
  *          "return" :
- *            - "outer" : "dart.core.List"
+ *            - "outer" : "dart-core.List"
  *              "inner" :
- *                - "outer" : "dart.core.String"
+ *                - "outer" : "dart-core.String"
  *                  "inner" :
  *
  *        Map<String, List<int>>
  *          "return" :
- *            - "outer" : "dart.core.Map"
+ *            - "outer" : "dart-core.Map"
  *              "inner" :
- *                - "outer" : "dart.core.String"
+ *                - "outer" : "dart-core.String"
  *                  "inner" :
- *                - "outer" : "dart.core.List"
+ *                - "outer" : "dart-core.List"
  *                  "inner" :
- *                    - "outer" : "dart.core.int"
+ *                    - "outer" : "dart-core.int"
  *                      "inner" :
  */
 class Type {
   String outer;
   List<Type> inner;
 
   Type(this.outer, this.inner);
 
   Map toMap() => {
     'outer': outer,
     '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
   };
-}
+}
+
+/// Given a mirror, returns its qualified name, but following the conventions

[terry, 2013/10/30 18:11:31]

Is this an internal representation that isn't exposed to the user?  A user would
never use import "dart-core:Map" but "dart:Map".

[Alan Knight, 2013/10/30 18:31:33]

This is what goes into the JSON now, and it's exposed to the user in the sense
that it's what's used in the URLs, which are now always of the form
#package/library-name.class.method#anythingExtraWeNeed

The names will display with normal punctuation. dart:core.Map (although we
normally would just use the simple names)

+/// we're using in Dartdoc, which is that library names with dots in them
+/// have them replaced with hyphens.
+String docName(DeclarationMirror m) {
+  if (m is LibraryMirror) {
+    return (m as LibraryMirror).qualifiedName.replaceAll('.','-');
+  }
+  var owner = m.owner;
+  if (owner == null) return m.qualifiedName;
+  // For the unnamed constructor we just return the class name.
+  if (m.simpleName == '') return docName(owner);
+  return docName(owner) + '.' + m.simpleName;
+}