Fix package docnames for select return types, and some more docgen refactoring.

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.
 ///
 ///      $ dart docgen.dart [OPTIONS] [FILE/DIR]
@@ skipping 68 matching lines @@
 [pub.dartlang.org](http://pub.dartlang.org).
 
 The main site for learning and using Dart is
 [www.dartlang.org](http://www.dartlang.org).
 Check out these pages:
 
   * [Dart homepage](http://www.dartlang.org)
   * [Tutorials](http://www.dartlang.org/docs/tutorials/)
   * [Programmer's Guide](http://www.dartlang.org/docs/)
   * [Samples](http://www.dartlang.org/samples/)
-  * [A Tour of the Dart Libraries](http://www.dartlang.org/docs/dart-up-and-runn
-ing/contents/ch03.html)
+  * [A Tour of the Dart Libraries](http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html)
 
 This API reference is automatically generated from the source code in the
 [Dart project](https://code.google.com/p/dart/).
 If you'd like to contribute to this documentation, see
 [Contributing](https://code.google.com/p/dart/wiki/Contributing)
 and
-[Writing API Documentation](https://code.google.com/p/dart/wiki/WritingApiDocume
-ntation).
+[Writing API Documentation](https://code.google.com/p/dart/wiki/WritingApiDocumentation).
 """;
 
 // TODO(efortuna): The use of this field is odd (this is based on how it was
 // originally used. Try to cleanup.
 /// Index of all indexable items. This also ensures that no class is
 /// created more than once.
 Map<String, Indexable> entityMap = new Map<String, Indexable>();
 
-/// Index of all the dart2js mirrors examined to corresponding MirrorBased
-/// docgen objects.
+/// Docgen constructor initializes the link resolver for markdown parsing.
+/// Also initializes the command line arguments.
 ///
-/// Used for lookup because of the dart2js mirrors exports
-/// issue. The second level map is indexed by owner docName for faster lookup.
-/// Why two levels of lookup? Speed, man. Speed.
-Map<String, Map<String, Set<MirrorBased>>> mirrorToDocgen =
-    new Map<String, Map<String, Set<MirrorBased>>>();
+/// [packageRoot] is the packages directory of the directory being analyzed.
+/// If [includeSdk] is `true`, then any SDK libraries explicitly imported will
+/// also be documented.
+/// If [parseSdk] is `true`, then all Dart SDK libraries will be documented.
+/// This option is useful when only the SDK libraries are needed.
+///
+/// Returned Future completes with true if document generation is successful.
+Future<bool> docgen(List<String> files, {String packageRoot,
+    bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false,
+    bool parseSdk: false, bool append: false, String introFileName: '',
+    out: _DEFAULT_OUTPUT_DIRECTORY, List<String> excludeLibraries : const [],
+    bool includeDependentPackages: false}) {
+  return _Generator.generateDocumentation(files, packageRoot: packageRoot,
+      outputToYaml: outputToYaml, includePrivate: includePrivate,
+      includeSdk: includeSdk, parseSdk: parseSdk, append: append,
+      introFileName: introFileName, out: out,
+      excludeLibraries: excludeLibraries,
+      includeDependentPackages: includeDependentPackages);
+}
 
-/// Given a Dart2jsMirror, find the corresponding Docgen [MirrorBased] object.
-///
-/// We have this global lookup function to avoid re-implementing looking up the
-/// scoping rules for comment resolution here (it is currently done in mirrors).
-/// If no corresponding MirrorBased object is found, we return a [DummyMirror]
-/// that simply returns the original mirror's qualifiedName while behaving like
-/// a MirrorBased object.
-MirrorBased getDocgenObject(DeclarationMirror mirror, [Indexable owner]) {
-  Map<String, Set<MirrorBased>> docgenObj =
-      mirrorToDocgen[mirror.qualifiedName];
-  if (docgenObj == null) {
-    return new DummyMirror(mirror, owner);
-  }
+/// Analyzes set of libraries by getting a mirror system and triggers the
+/// documentation of the libraries.
+Future<MirrorSystem> getMirrorSystem(List<Uri> libraries,
+    {String packageRoot, bool parseSdk: false}) {
+  if (libraries.isEmpty) throw new StateError('No Libraries.');
 
-  Set<MirrorBased> results = new Set<MirrorBased>();
-  var setToExamine = new Set();
-  if (owner != null) {
-    var firstSet = docgenObj[owner.docName];
-    if (firstSet != null) setToExamine.addAll(firstSet);
-    if (Indexable._coreLibrary != null &&
-        docgenObj[Indexable._coreLibrary.docName] != null) {
-      setToExamine.addAll(docgenObj[Indexable._coreLibrary.docName]);
-    }
-  } else {
-    for (var value in docgenObj.values) {
-      setToExamine.addAll(value);
-    }
-  }
-
-  for(MirrorBased mirrorBased in setToExamine) {
-    // This check makes me sad, but Dart doesn't seem to be dynamic enough to
-    // write this another way. Dart2js and the editor didn't like the Type
-    // lookup in a map.
-    if (mirrorBased.mirror.qualifiedName == mirror.qualifiedName &&
-        ((mirror is ClassMirror && mirrorBased is Class)
-        || (mirror is LibraryMirror && mirrorBased is Library)
-        || (mirror is MethodMirror && mirrorBased is Method)
-        || (mirror is VariableMirror && mirrorBased is Variable)
-        || (mirror is TypedefMirror && mirrorBased is Typedef)
-        || (mirror is TypeMirror && mirrorBased is Type)
-        || (mirror is InstanceMirror && mirrorBased is Annotation))) {
-      results.add(mirrorBased);
-    }
-  }
-
-  if (results.length > 0) {
-    return results.first; // This might occur if we didn't specify an "owner."
-  }
-  return new DummyMirror(mirror, owner);
+  // Finds the root of SDK library based off the location of docgen.
+  var root = _Generator._rootDirectory;
+  var sdkRoot = path.normalize(path.absolute(path.join(root, 'sdk')));
+  _Generator.logger.info('SDK Root: ${sdkRoot}');
+  return _Generator._analyzeLibraries(libraries, sdkRoot,
+      packageRoot: packageRoot);
 }
 
 /// For types that we do not explicitly create or have not yet created in our
 /// entity map (like core types).
-class DummyMirror implements MirrorBased {
+class DummyMirror implements Indexable {
   DeclarationMirror mirror;
   /// The library that contains this element, if any. Used as a hint to help
   /// determine which object we're referring to when looking up this mirror in
   /// our map.
   Indexable owner;
   DummyMirror(this.mirror, [this.owner]);
 
   String get docName {
     if (mirror == null) return '';
     if (mirror is LibraryMirror) {
       return mirror.qualifiedName.replaceAll('.','-');
     }
     var mirrorOwner = mirror.owner;
     if (mirrorOwner == null) return mirror.qualifiedName;
     var simpleName = mirror.simpleName;
     if (mirror is MethodMirror && (mirror as MethodMirror).isConstructor) {
-      // We name constructors specially -- including the class name again and a
+      // We name constructors specially -- repeating the class name and a
       // "-" to separate the constructor from its name (if any).
       simpleName = '${mirrorOwner.simpleName}-$simpleName';
     }
-    return getDocgenObject(mirrorOwner, owner).docName + '.' + simpleName;
+    return Indexable.getDocgenObject(mirrorOwner, owner).docName + '.' +
+        simpleName;
   }
-  List<Annotation> _createAnnotations(DeclarationMirror mirror,
-      Library owningLibrary) => null;
 
   bool get isPrivate => mirror == null? false : mirror.isPrivate;
+
+  String get packageName {
+    var libMirror = _getOwningLibraryFromMirror(mirror);
+    if (libMirror != null) {
+      return Library._packageName(libMirror);
+    }
+    return '';
+  }
+
+  String get packagePrefix => packageName == null || packageName.isEmpty ?
+      '' : '$packageName/';
+
+  LibraryMirror _getOwningLibraryFromMirror(DeclarationMirror mirror) {
+    if (mirror is LibraryMirror) return mirror;
+    if (mirror == null) return null;
+    return _getOwningLibraryFromMirror(mirror.owner);
+  }
 }
 
+/// Docgen representation of an item to be documented, that wraps around a
+/// dart2js mirror.
 abstract class MirrorBased {
   DeclarationMirror get mirror;
-  MirrorBased owner;
-
-  /// Returns this object's qualified name, but following the conventions
-  /// we're using in Dartdoc, which is that library names with dots in them
-  /// have them replaced with hyphens.
-  String get docName => owner.docName + '.' + mirror.simpleName;
 
   /// Returns a list of meta annotations assocated with a mirror.
   List<Annotation> _createAnnotations(DeclarationMirror mirror,
       Library owningLibrary) {
     var annotationMirrors = mirror.metadata.where((e) =>
         e is dart2js.Dart2JsConstructedConstantMirror);
     var annotations = [];
     annotationMirrors.forEach((annotation) {
       var docgenAnnotation = new Annotation(annotation, owningLibrary);
       if (!_SKIPPED_ANNOTATIONS.contains(
           docgenAnnotation.mirror.qualifiedName)) {
         annotations.add(docgenAnnotation);
       }
     });
     return annotations;
   }
-
-  bool get isPrivate => false;
-}
-
-/// Docgen constructor initializes the link resolver for markdown parsing.
-/// Also initializes the command line arguments.
-///
-/// [packageRoot] is the packages directory of the directory being analyzed.
-/// If [includeSdk] is `true`, then any SDK libraries explicitly imported will
-/// also be documented.
-/// If [parseSdk] is `true`, then all Dart SDK libraries will be documented.
-/// This option is useful when only the SDK libraries are needed.
-///
-/// Returned Future completes with true if document generation is successful.
-Future<bool> docgen(List<String> files, {String packageRoot,
-    bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false,
-    bool parseSdk: false, bool append: false, String introFileName: '',
-    out: _DEFAULT_OUTPUT_DIRECTORY, List<String> excludeLibraries : const [],
-    bool includeDependentPackages: false}) {
-  return _Generator.generateDocumentation(files, packageRoot: packageRoot,
-      outputToYaml: outputToYaml, includePrivate: includePrivate,
-      includeSdk: includeSdk, parseSdk: parseSdk, append: append,
-      introFileName: introFileName, out: out,
-      excludeLibraries: excludeLibraries,
-      includeDependentPackages: includeDependentPackages);
-}
-
-/// Analyzes set of libraries by getting a mirror system and triggers the
-/// documentation of the libraries.
-Future<MirrorSystem> getMirrorSystem(List<Uri> libraries,
-    {String packageRoot, bool parseSdk: false}) {
-  if (libraries.isEmpty) throw new StateError('No Libraries.');
-  // Finds the root of SDK library based off the location of docgen.
-
-  var root = _Generator._rootDirectory;
-  var sdkRoot = path.normalize(path.absolute(path.join(root, 'sdk')));
-  _Generator.logger.info('SDK Root: ${sdkRoot}');
-  return _Generator._analyzeLibraries(libraries, sdkRoot,
-      packageRoot: packageRoot);
 }
 
 class _Generator {
   static var _outputDirectory;
 
   /// This is set from the command line arguments flag --include-private
   static bool _includePrivate = false;
 
   /// Library names to explicitly exclude.
   ///
@@ skipping 54 matching lines @@
             (includeSdk || parseSdk) ? Indexable._sdkLibraries : []);
         librariesToDocument.removeWhere(
             (x) => _excluded.contains(x.simpleName));
         _documentLibraries(librariesToDocument, includeSdk: includeSdk,
             outputToYaml: outputToYaml, append: append, parseSdk: parseSdk,
             introFileName: introFileName);
         return true;
       });
   }
 
-  /// Writes text to a file in the output directory.
+  /// Writes [text] to a file in the output directory.
   static void _writeToFile(String text, String filename, {bool append: false}) {
     if (text == null) return;
     Directory dir = new Directory(_outputDirectory);
     if (!dir.existsSync()) {
       dir.createSync();
     }
     if (path.split(filename).length > 1) {
       var splitList = path.split(filename);
       for (int i = 0; i < splitList.length; i++) {
         var level = splitList[i];
@@ skipping 269 matching lines @@
     var sdk = new List<Uri>();
     LIBRARIES.forEach((String name, LibraryInfo info) {
       if (info.documented) {
         sdk.add(Uri.parse('dart:$name'));
         logger.info('Add to SDK: ${sdk.last}');
       }
     });
     return sdk;
   }
 
-  static bool _isFullChainVisible(MirrorBased item) {
-    // TODO: reconcile with isVisible
+  static bool _isFullChainVisible(Indexable item) {
+    // TODO: reconcile with isVisible.
+    // TODO: Also should be able to take MirrorBased items in general probably.
     var result = _includePrivate || (!item.isPrivate && (item.owner != null ?
         _isFullChainVisible(item.owner) : true));
     return result;
   }
 
   /// Currently left public for testing purposes. :-/
   static Library generateLibrary(dart2js.Dart2JsLibraryMirror library) {
     var result = new Library(library);
     result._findPackage(library);
     logger.fine('Generated library for ${result.name}');
     return result;
   }
 }
 
 /// An item that is categorized in our mirrorToDocgen map, as a distinct,
 /// searchable element.
 ///
 /// These are items that refer to concrete entities (a Class, for example,
 /// but not a Type, which is a "pointer" to a class) that we wish to be
 /// globally resolvable. This includes things such as class methods and
 /// variables, but parameters for methods are not "Indexable" as we do not want
 /// the user to be able to search for a method based on its parameter names!
 /// The set of indexable items also includes Typedefs, since the user can refer
 /// to them as concrete entities in a particular scope.
-class Indexable extends MirrorBased {
+abstract class Indexable extends MirrorBased {
   /// The dart:core library, which contains all types that are always available
   /// without import.
   static Library _coreLibrary;
 
   /// Set of libraries declared in the SDK, so libraries that can be accessed
   /// when running dart by default.
   static Iterable<LibraryMirror> _sdkLibraries;
 
   String get qualifiedName => fileName;
   bool isPrivate;
   DeclarationMirror mirror;
   /// The comment text pre-resolution. We keep this around because inherited
   /// methods need to resolve links differently from the superclass.
   String _unresolvedComment = '';
 
   // TODO(janicejl): Make MDN content generic or pluggable. Maybe move
   // MDN-specific code to its own library that is imported into the default
   // impl?
   /// Map of all the comments for dom elements from MDN.
   static Map _mdn;
 
+  /// Index of all the dart2js mirrors examined to corresponding MirrorBased
+  /// docgen objects.
+  ///
+  /// Used for lookup because of the dart2js mirrors exports
+  /// issue. The second level map is indexed by owner docName for faster lookup.
+  /// Why two levels of lookup? Speed, man. Speed.
+  static Map<String, Map<String, Set<Indexable>>> _mirrorToDocgen =
+      new Map<String, Map<String, Set<Indexable>>>();
+
   Indexable(this.mirror) {
     this.isPrivate = _isHidden(mirror);
 
-    var map = mirrorToDocgen[this.mirror.qualifiedName];
-    if (map == null) map = new Map<String, Set<MirrorBased>>();
+    var map = _mirrorToDocgen[this.mirror.qualifiedName];
+    if (map == null) map = new Map<String, Set<Indexable>>();
 
     var set = map[owner.docName];
-    if (set == null) set = new Set<MirrorBased>();
+    if (set == null) set = new Set<Indexable>();
     set.add(this);
     map[owner.docName] = set;
-    mirrorToDocgen[this.mirror.qualifiedName] = map;
+    _mirrorToDocgen[this.mirror.qualifiedName] = map;
   }
 
   /** Walk up the owner chain to find the owning library. */
   Library _getOwningLibrary(Indexable indexable) {
     if (indexable is Library) return indexable;
-    // TODO: is this needed?
-    if (indexable is DummyMirror) return getDocgenObject(indexable.mirror.library);
     return _getOwningLibrary(indexable.owner);
   }
 
   static initializeTopLevelLibraries(MirrorSystem mirrorSystem) {
     _sdkLibraries = mirrorSystem.libraries.values.where(
         (each) => each.uri.scheme == 'dart');
     _coreLibrary = new Library(_sdkLibraries.singleWhere((lib) =>
         lib.uri.toString().startsWith('dart:core')));
   }
 
+  /// Returns this object's qualified name, but following the conventions
+  /// we're using in Dartdoc, which is that library names with dots in them
+  /// have them replaced with hyphens.
+  String get docName;
+
   markdown.Node fixReferenceWithScope(String name) => null;
 
   /// Converts all [foo] references in comments to <a>libraryName.foo</a>.
   markdown.Node fixReference(String name) {
     // Attempt the look up the whole name up in the scope.
     String elementName = findElementInScope(name);
     if (elementName != null) {
       return new markdown.Element.text('a', elementName);
     }
     return _fixComplexReference(name);
@@ skipping 29 matching lines @@
     if (_comment.isEmpty) {
       _comment = _mdnComment();
     }
     return _comment;
   }
 
   set comment(x) => _comment = x;
 
   String get name => mirror.simpleName;
 
-  MirrorBased get owner => new DummyMirror(mirror.owner);
+  Indexable get owner => new DummyMirror(mirror.owner);
 
   /// Generates MDN comments from database.json.
   String _mdnComment() {
     //Check if MDN is loaded.
     if (_mdn == null) {
       // Reading in MDN related json file.
       var root = _Generator._rootDirectory;
       var mdnPath = path.join(root, 'utils/apidoc/mdn/database.json');
       _mdn = JSON.decode(new File(mdnPath).readAsStringSync());
     }
@@ skipping 316 matching lines @@
   }
 
   Map _filterMap(exported, map, test) {
     map.forEach((key, value) {
       if (test(key, value)) exported[key] = value;
     });
     return exported;
   }
 
   bool get _isVisible => _Generator._includePrivate || !isPrivate;
+
+  /// Given a Dart2jsMirror, find the corresponding Docgen [MirrorBased] object.
+  ///
+  /// We have this global lookup function to avoid re-implementing looking up
+  /// the scoping rules for comment resolution here (it is currently done in
+  /// mirrors). If no corresponding MirrorBased object is found, we return a
+  /// [DummyMirror] that simply returns the original mirror's qualifiedName
+  /// while behaving like a MirrorBased object.
+  static Indexable getDocgenObject(DeclarationMirror mirror,
+    [Indexable owner]) {
+    Map<String, Set<Indexable>> docgenObj =
+        _mirrorToDocgen[mirror.qualifiedName];
+    if (docgenObj == null) {
+      return new DummyMirror(mirror, owner);
+    }
+
+    var setToExamine = new Set();
+    if (owner != null) {
+      var firstSet = docgenObj[owner.docName];
+      if (firstSet != null) setToExamine.addAll(firstSet);
+      if (_coreLibrary != null &&
+          docgenObj[_coreLibrary.docName] != null) {
+        setToExamine.addAll(docgenObj[_coreLibrary.docName]);
+      }
+    } else {
+      for (var value in docgenObj.values) {
+        setToExamine.addAll(value);
+      }
+    }
+
+    Set<Indexable> results = new Set<Indexable>();
+    for(Indexable indexable in setToExamine) {
+      if (indexable.mirror.qualifiedName == mirror.qualifiedName &&
+          indexable._isValidMirror(mirror)) {
+        results.add(indexable);
+      }
+    }
+
+    if (results.length > 0) {
+      // This might occur if we didn't specify an "owner."
+      return results.first;
+    }
+    return new DummyMirror(mirror, owner);
+  }
+
+  bool _isValidMirror(DeclarationMirror mirror);
 }
 
 /// 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.
   Map<String, Method> functions;
 
   Map<String, Class> classes = {};
   Map<String, Typedef> typedefs = {};
   Map<String, Class> errors = {};
 
   String packageName = '';
   bool hasBeenCheckedForPackage = false;
   String packageIntro;
 
   /// Returns the [Library] for the given [mirror] if it has already been
   /// created, else creates it.
   factory Library(LibraryMirror mirror) {
-    var library = getDocgenObject(mirror);
+    var library = Indexable.getDocgenObject(mirror);
     if (library is DummyMirror) {
       library = new Library._(mirror);
     }
     return library;
   }
 
   Library._(LibraryMirror libraryMirror) : super(libraryMirror) {
     var exported = _calcExportedItems(libraryMirror);
     var exportedClasses = exported['classes']..addAll(libraryMirror.classes);
     _findPackage(mirror);
     classes = {};
     typedefs = {};
     errors = {};
     exportedClasses.forEach((String mirrorName, ClassMirror classMirror) {
         if (classMirror.isTypedef) {
           // This is actually a Dart2jsTypedefMirror, and it does define value,
           // but we don't have visibility to that type.
           var mirror = classMirror;
           if (_Generator._includePrivate || !mirror.isPrivate) {
-            entityMap[getDocgenObject(mirror).docName] =
-                new Typedef(mirror, this);
-            typedefs[mirror.simpleName] =
-                entityMap[getDocgenObject(mirror).docName];
+            var aTypedef = new Typedef(mirror, this);
+            entityMap[Indexable.getDocgenObject(mirror).docName] = aTypedef;
+            typedefs[mirror.simpleName] = aTypedef;
           }
         } else {
           var clazz = new Class(classMirror, this);
 
           if (clazz.isError()) {
             errors[classMirror.simpleName] = clazz;
           } else if (classMirror.isClass) {
             classes[classMirror.simpleName] = clazz;
           } else {
             throw new ArgumentError(
                 '${classMirror.simpleName} - no class type match. ');
           }
         }
     });
     this.functions =  _createMethods(exported['methods']
       ..addAll(libraryMirror.functions), this);
     this.variables = _createVariables(exported['variables']
       ..addAll(libraryMirror.variables), this);
   }
 
   /// Look for the specified name starting with the current member, and
   /// progressively working outward to the current library scope.
   String findElementInScope(String name) {
     var lookupFunc = Indexable.determineLookupFunc(name);
     var libraryScope = lookupFunc(mirror, name);
     if (libraryScope != null) {
-      var result = getDocgenObject(libraryScope, this);
+      var result = Indexable.getDocgenObject(libraryScope, this);
       if (result is DummyMirror) return packagePrefix + result.docName;
       return result.packagePrefix + result.docName;
     }
     return super.findElementInScope(name);
   }
 
   /// For a library's [mirror], determine the name of the package (if any) we
   /// believe it came from (because of its file URI).
   ///
   /// If no package could be determined, we return an empty string.
   String _findPackage(LibraryMirror mirror) {
     if (mirror == null) return '';
     if (hasBeenCheckedForPackage) return packageName;
     hasBeenCheckedForPackage = true;
     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');
-    packageName = _packageName(pubspec);
+    packageName = _packageName(mirror);
     // Associate the package readme with all the libraries. This is a bit
     // wasteful, but easier than trying to figure out which partial match
     // is best.
-    packageIntro = _packageIntro(rootdir);
+    packageIntro = _packageIntro(_getRootdir(mirror));
     return packageName;
   }
 
   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)
           .startsWith('README'))).toList();
     if (readmes.isEmpty) return '';
     // If there are multiples, pick the shortest name.
     readmes.sort((a, b) => a.path.length.compareTo(b.path.length));
     var readme = readmes.first;
     var linkResolver = (name) => Indexable.globalFixReference(name);
     var contents = markdown.markdownToHtml(readme
       .readAsStringSync(), linkResolver: linkResolver,
       inlineSyntaxes: _MARKDOWN_SYNTAXES);
     return contents;
   }
 
+  /// Given a LibraryMirror that is a library, return the name of the directory
+  /// holding that library.
+  static String _getRootdir(LibraryMirror mirror) =>
+      path.dirname(path.dirname(mirror.uri.toFilePath()));
+
   /// Read a pubspec and return the library name.
-  String _packageName(String pubspecName) {
+  static String _packageName(LibraryMirror mirror) {
+    if (mirror.uri.scheme != 'file') return '';
+    var rootdir = _getRootdir(mirror);
+    var pubspecName = path.join(rootdir, 'pubspec.yaml');
     File pubspec = new File(pubspecName);
     if (!pubspec.existsSync()) return '';
     var contents = pubspec.readAsStringSync();
     var spec = loadYaml(contents);
     return spec["name"];
   }
 
   markdown.Node fixReferenceWithScope(String name) => fixReference(name);
 
   String get packagePrefix => packageName == null || packageName.isEmpty ?
@@ skipping 91 matching lines @@
         .map((e) => e.previewMap).toList(),
       'typedef': recurseMap(typedefs),
       'error': errors.values.where((e) => e._isVisible)
           .map((e) => e.previewMap).toList()
     },
     'packageName': packageName,
     'packageIntro' : packageIntro
   };
 
   String get typeName => 'library';
+
+  bool _isValidMirror(DeclarationMirror mirror) => mirror is LibraryMirror;
+}
+
+abstract class OwnedIndexable extends Indexable {
+  Indexable owner;
+
+  /// Returns this object's qualified name, but following the conventions
+  /// we're using in Dartdoc, which is that library names with dots in them
+  /// have them replaced with hyphens.
+  String get docName => owner.docName + '.' + mirror.simpleName;
+
+  OwnedIndexable(DeclarationMirror mirror, this.owner) : super(mirror);
 }
 
 /// A class containing contents of a Dart class.
-class Class extends Indexable implements Comparable {
+class Class extends OwnedIndexable implements Comparable {
 
   /// List of the names of interfaces that this class implements.
   List<Class> interfaces = [];
 
   /// Names of classes that extends or implements this class.
   Set<Class> subclasses = new Set<Class>();
 
   /// Top-level variables in the class.
   Map<String, Variable> variables;
 
@@ skipping 10 matching lines @@
 
   Class superclass;
   bool isAbstract;
 
   /// List of the meta annotations on the class.
   List<Annotation> annotations;
 
   /// Make sure that we don't check for inherited comments more than once.
   bool _commentsEnsured = false;
 
-  Indexable owner;
-
   /// Returns the [Class] for the given [mirror] if it has already been created,
   /// else creates it.
   factory Class(ClassMirror mirror, Library owner) {
-    var clazz = getDocgenObject(mirror, owner);
+    var clazz = Indexable.getDocgenObject(mirror, owner);
     if (clazz is DummyMirror) {
       clazz = new Class._(mirror, owner);
       entityMap[clazz.docName] = clazz;
     }
     return clazz;
   }
 
   /// Called when we are constructing a superclass or interface class, but it
   /// is not known if it belongs to the same owner as the original class. In
   /// this case, we create an object whose owner is what the original mirror
   /// says it is.
   factory Class._possiblyDifferentOwner(ClassMirror mirror,
       Library originalOwner) {
     if (mirror.owner is LibraryMirror) {
-      var realOwner = getDocgenObject(mirror.owner);
+      var realOwner = Indexable.getDocgenObject(mirror.owner);
       if (realOwner is Library) {
         return new Class(mirror, realOwner);
       } else {
         return new Class(mirror, originalOwner);
       }
     } else {
       return new Class(mirror, originalOwner);
     }
   }
 
-  Class._(ClassMirror classMirror, this.owner) : super(classMirror) {
+  Class._(ClassMirror classMirror, Indexable owner) :
+      super(classMirror, owner) {
     inheritedVariables = {};
 
     // The reason we do this madness is the superclass and interface owners may
     // not be this class's owner!! Example: BaseClient in http pkg.
     var superinterfaces = classMirror.superinterfaces.map(
         (interface) => new Class._possiblyDifferentOwner(interface, owner));
     this.superclass = classMirror.superclass == null? null :
         new Class._possiblyDifferentOwner(classMirror.superclass, owner);
 
     interfaces = superinterfaces.toList();
@@ skipping 17 matching lines @@
   }
 
   String get packagePrefix => owner.packagePrefix;
 
   String _lookupInClassAndSuperclasses(String name) {
     var lookupFunc = Indexable.determineLookupFunc(name);
     var classScope = this;
     while (classScope != null) {
       var classFunc = lookupFunc(classScope.mirror, name);
       if (classFunc != null) {
-        return packagePrefix + getDocgenObject(classFunc, owner).docName;
+        return packagePrefix + Indexable.getDocgenObject(classFunc, owner).docName;
       }
       classScope = classScope.superclass;
     }
     return null;
   }
 
   /// Look for the specified name starting with the current member, and
   /// progressively working outward to the current library scope.
   String findElementInScope(String name) {
     var lookupFunc = Indexable.determineLookupFunc(name);
@@ skipping 24 matching lines @@
     inheritedVariables.addAll(_allButStatics(superclass.variables));
     addInheritedMethod(superclass, this);
   }
 
   /** [newParent] refers to the actual class is currently using these methods.
    * which may be different because with the mirror system, we only point to the
    * original canonical superclasse's method.
    */
   void addInheritedMethod(Class parent, Class newParent) {
     parent.inheritedMethods.forEach((name, method) {
-      if(!method.isConstructor){
+      if(!method.mirror.isConstructor){
         inheritedMethods[name] = new Method(method.mirror, newParent, method);
       }}
     );
     _allButStatics(parent.methods).forEach((name, method) {
-      if (!method.isConstructor) {
+      if (!method.mirror.isConstructor) {
         inheritedMethods[name] = new Method(method.mirror, newParent, method);
       }}
     );
   }
 
   /// Remove statics from the map of inherited items before adding them.
   Map _allButStatics(Map items) {
     var result = {};
     items.forEach((name, item) {
       if (!item.isStatic) {
@@ skipping 73 matching lines @@
         .map((x) => x.qualifiedName).toList(),
     'variables': recurseMap(variables),
     'inheritedVariables': recurseMap(inheritedVariables),
     'methods': expandMethodMap(methods),
     'inheritedMethods': expandMethodMap(inheritedMethods),
     'annotations': annotations.map((a) => a.toMap()).toList(),
     'generics': recurseMap(generics)
   };
 
   int compareTo(aClass) => name.compareTo(aClass.name);
+
+  bool _isValidMirror(DeclarationMirror mirror) => mirror is ClassMirror;
 }
 
-class Typedef extends Indexable {
+class Typedef extends OwnedIndexable {
   String returnType;
 
   Map<String, Parameter> parameters;
 
   /// Generic information about the typedef.
   Map<String, Generic> generics;
 
   /// List of the meta annotations on the typedef.
   List<Annotation> annotations;
 
   /// Returns the [Library] for the given [mirror] if it has already been
   /// created, else creates it.
   factory Typedef(TypedefMirror mirror, Library owningLibrary) {
-    var aTypedef = getDocgenObject(mirror, owningLibrary);
+    var aTypedef = Indexable.getDocgenObject(mirror, owningLibrary);
     if (aTypedef is DummyMirror) {
       aTypedef = new Typedef._(mirror, owningLibrary);
     }
     return aTypedef;
   }
 
-  Typedef._(TypedefMirror mirror, Library owningLibrary) : super(mirror) {
-    owner = owningLibrary;
-    returnType = getDocgenObject(mirror.value.returnType).docName;
+  Typedef._(TypedefMirror mirror, Library owningLibrary) :
+      super(mirror, owningLibrary) {
+    returnType = Indexable.getDocgenObject(mirror.value.returnType).docName;
     generics = _createGenerics(mirror);
     parameters = _createParameters(mirror.value.parameters, owningLibrary);
     annotations = _createAnnotations(mirror, owningLibrary);
   }
 
   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';
+
+  bool _isValidMirror(DeclarationMirror mirror) => mirror is TypedefMirror;
 }
 
 /// A class containing properties of a Dart variable.
-class Variable extends Indexable {
+class Variable extends OwnedIndexable {
 
   bool isFinal;
   bool isStatic;
   bool isConst;
   Type type;
   String _variableName;
-  Indexable owner;
 
   /// List of the meta annotations on the variable.
   List<Annotation> annotations;
 
   factory Variable(String variableName, VariableMirror mirror,
       Indexable owner) {
-    var variable = getDocgenObject(mirror);
+    var variable = Indexable.getDocgenObject(mirror);
     if (variable is DummyMirror) {
       return new Variable._(variableName, mirror, owner);
     }
     return variable;
   }
 
-  Variable._(this._variableName, VariableMirror mirror, this.owner) :
-      super(mirror) {
+  Variable._(this._variableName, VariableMirror mirror, Indexable owner) :
+      super(mirror, owner) {
     isFinal = mirror.isFinal;
     isStatic = mirror.isStatic;
     isConst = mirror.isConst;
     type = new Type(mirror.type, _getOwningLibrary(owner));
     annotations = _createAnnotations(mirror, _getOwningLibrary(owner));
   }
 
   String get name => _variableName;
 
   /// Generates a map describing the [Variable] object.
@@ skipping 19 matching lines @@
     }
     return super.comment;
   }
 
   markdown.Node fixReferenceWithScope(String name) => fixReference(name);
 
   String findElementInScope(String name) {
     var lookupFunc = Indexable.determineLookupFunc(name);
     var result = lookupFunc(mirror, name);
     if (result != null) {
-      result = getDocgenObject(result);
+      result = Indexable.getDocgenObject(result);
       if (result is DummyMirror) return packagePrefix + result.docName;
       return result.packagePrefix + result.docName;
     }
 
     if (owner != null) {
       var result = owner.findElementInScope(name);
       if (result != null) {
         return result;
       }
     }
     return super.findElementInScope(name);
   }
+
+  bool _isValidMirror(DeclarationMirror mirror) => mirror is VariableMirror;
 }
 
 /// A class containing properties of a Dart method.
-class Method extends Indexable {
+class Method extends OwnedIndexable {
 
   /// Parameters for this method.
   Map<String, Parameter> parameters;
 
   bool isStatic;
   bool isAbstract;
   bool isConst;
-  bool isConstructor;
-  bool isGetter;
-  bool isSetter;
-  bool isOperator;
   Type returnType;
   Method methodInheritedFrom;
 
   /// Qualified name to state where the comment is inherited from.
   String commentInheritedFrom = "";
 
   /// List of the meta annotations on the method.
   List<Annotation> annotations;
 
-  Indexable owner;
-
   factory Method(MethodMirror mirror, Indexable owner, // Indexable newOwner.
       [Method methodInheritedFrom]) {
-    var method = getDocgenObject(mirror, owner);
+    var method = Indexable.getDocgenObject(mirror, owner);
     if (method is DummyMirror) {
       method = new Method._(mirror, owner, methodInheritedFrom);
     }
     return method;
   }
 
-  Method._(MethodMirror mirror, this.owner, this.methodInheritedFrom)
-      : super(mirror) {
-    this.isStatic = mirror.isStatic;
-    this.isAbstract = mirror.isAbstract;
-    this.isConst = mirror.isConstConstructor;
-    this.returnType = new Type(mirror.returnType, _getOwningLibrary(owner));
-    this.parameters = _createParameters(mirror.parameters, owner);
-    this.annotations = _createAnnotations(mirror, _getOwningLibrary(owner));
-    this.isConstructor = mirror.isConstructor;
-    this.isGetter = mirror.isGetter;
-    this.isSetter = mirror.isSetter;
-    this.isOperator = mirror.isOperator;
+  Method._(MethodMirror mirror, Indexable owner, this.methodInheritedFrom)
+      : super(mirror, owner) {
+    isStatic = mirror.isStatic;
+    isAbstract = mirror.isAbstract;
+    isConst = mirror.isConstConstructor;
+    returnType = new Type(mirror.returnType, _getOwningLibrary(owner));
+    parameters = _createParameters(mirror.parameters, owner);
+    annotations = _createAnnotations(mirror, _getOwningLibrary(owner));
   }
 
   String get packagePrefix => owner.packagePrefix;
 
   Method get originallyInheritedFrom => methodInheritedFrom == null ?
       this : methodInheritedFrom.originallyInheritedFrom;
 
   markdown.Node fixReferenceWithScope(String name) => fixReference(name);
 
   /// Look for the specified name starting with the current member, and
   /// progressively working outward to the current library scope.
   String findElementInScope(String name) {
     var lookupFunc = Indexable.determineLookupFunc(name);
 
     var memberScope = lookupFunc(this.mirror, name);
     if (memberScope != null) {
       // do we check for a dummy mirror returned here and look up with an owner
       // higher ooooor in getDocgenObject do we include more things in our
       // lookup
-      var result = getDocgenObject(memberScope, owner);
+      var result = Indexable.getDocgenObject(memberScope, owner);
       if (result is DummyMirror && owner.owner != null
           && owner.owner is! DummyMirror) {
-        var aresult = getDocgenObject(memberScope, owner.owner);
+        var aresult = Indexable.getDocgenObject(memberScope, owner.owner);
         if (aresult is! DummyMirror) result = aresult;
       }
       if (result is DummyMirror) return packagePrefix + result.docName;
       return result.packagePrefix + result.docName;
     }
 
     if (owner != null) {
       var result = owner.findElementInScope(name);
       if (result != null) return result;
     }
@@ skipping 33 matching lines @@
     'inheritedFrom': (methodInheritedFrom == null? '' :
         originallyInheritedFrom.docName),
     'static': isStatic.toString(),
     'abstract': isAbstract.toString(),
     'constant': isConst.toString(),
     'return': new List.filled(1, returnType.toMap()),
     'parameters': recurseMap(parameters),
     'annotations': annotations.map((a) => a.toMap()).toList()
   };
 
-  String get typeName => isConstructor ? 'constructor' :
-    isGetter ? 'getter' : isSetter ? 'setter' :
-    isOperator ? 'operator' : 'method';
+  String get typeName {
+    MethodMirror theMirror = mirror;
+    if (theMirror.isConstructor) return 'constructor';
+    if (theMirror.isGetter) return 'getter';
+    if (theMirror.isSetter) return'setter';
+    if (theMirror.isOperator) return 'operator';
+    return 'method';
+  }
 
   get comment {
     if (_comment != null) return _comment;
     if (owner is Class) {
       (owner as Class).ensureComments();
     }
     var result = super.comment;
     if (result == '' && methodInheritedFrom != null) {
       // this should be NOT from the MIRROR, but from the COMMENT
       _unresolvedComment = methodInheritedFrom._unresolvedComment;
 
       var linkResolver = (name) => fixReferenceWithScope(name);
       comment = _unresolvedComment == null ? '' :
         markdown.markdownToHtml(_unresolvedComment.trim(),
             linkResolver: linkResolver, inlineSyntaxes: _MARKDOWN_SYNTAXES);
       commentInheritedFrom = methodInheritedFrom.commentInheritedFrom;
       result = comment;
     }
     return result;
   }
+
+  bool _isValidMirror(DeclarationMirror mirror) => mirror is MethodMirror;
 }
 
 /// Docgen wrapper around the dart2js mirror for a Dart
 /// method/function parameter.
 class Parameter extends MirrorBased {
   ParameterMirror mirror;
   String name;
   bool isOptional;
   bool isNamed;
   bool hasDefaultValue;
@@ skipping 58 matching lines @@
 ///            - "outer" : "dart-core.Map"
 ///              "inner" :
 ///                - "outer" : "dart-core.String"
 ///                  "inner" :
 ///                - "outer" : "dart-core.List"
 ///                  "inner" :
 ///                    - "outer" : "dart-core.int"
 ///                      "inner" :
 class Type extends MirrorBased {
   TypeMirror mirror;
-  MirrorBased owningLibrary;
+  Library owningLibrary;
 
   Type(this.mirror, this.owningLibrary);
 
   /// Returns a list of [Type] objects constructed from TypeMirrors.
   List<Type> _createTypeGenerics(TypeMirror mirror) {
     if (mirror is ClassMirror && !mirror.isTypedef) {
       var innerList = [];
       mirror.typeArguments.forEach((e) {
         innerList.add(new Type(e, owningLibrary));
       });
       return innerList;
     }
     return [];
   }
 
-  Map toMap() => {
-    // We may encounter types whose corresponding library has not been
-    // processed yet, so look up with the owningLibrary at the last moment.
-    'outer': getDocgenObject(mirror, owningLibrary).docName,
-    'inner': _createTypeGenerics(mirror).map((e) => e.toMap()).toList(),
-  };
+  Map toMap() {
+    var result = Indexable.getDocgenObject(mirror, owningLibrary);
+    return {
+      // We may encounter types whose corresponding library has not been
+      // processed yet, so look up with the owningLibrary at the last moment.
+      'outer': result.packagePrefix + result.docName,
+      'inner': _createTypeGenerics(mirror).map((e) => e.toMap()).toList(),
+    };
+  }
 }
 
 /// Holds the name of the annotation, and its parameters.
 class Annotation extends MirrorBased {
   List<String> parameters;
   /// The class of this annotation.
   ClassMirror mirror;
   Library owningLibrary;
 
   Annotation(InstanceMirror originalMirror, this.owningLibrary) {
     mirror = originalMirror.type;
     parameters = originalMirror.type.variables.values
         .where((e) => e.isFinal)
         .map((e) => originalMirror.getField(e.simpleName).reflectee)
         .where((e) => e != null)
         .toList();
   }
 
   Map toMap() => {
-    'name': getDocgenObject(mirror, owningLibrary).docName,
+    'name': Indexable.getDocgenObject(mirror, owningLibrary).docName,
     'parameters': parameters
   };
 }