Fix "inherited from" comments for Interceptor

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 27 matching lines @@
 
 /// Annotations that we do not display in the viewer.
 const List<String> _SKIPPED_ANNOTATIONS = const [
     'metadata.DocsEditable', '_js_helper.JSName', '_js_helper.Creates',
     '_js_helper.Returns'];
 
 /// Support for [:foo:]-style code comments to the markdown parser.
 List<markdown.InlineSyntax> _MARKDOWN_SYNTAXES =
   [new markdown.CodeSyntax(r'\[:\s?((?:.|\n)*?)\s?:\]')];
 
+/// If we can't find the SDK introduction text, which will happen if running
+/// from a snapshot and using --parse-sdk or --include-sdk, then use this
+/// hard-coded version. This should be updated to be consistent with the text
+/// in docgen/doc/sdk-introduction.md
+const DEFAULT_SDK_INTRODUCTION = """
+Welcome to the Dart API reference documentation,
+covering the official Dart API libraries.
+Some of the most fundamental Dart libraries include:
+
+* [dart:core](#dart:core):
+  Core functionality such as strings, numbers, collections, errors,
+  dates, and URIs.
+* [dart:html](#dart:html):
+  DOM manipulation for web apps.
+* [dart:io](#dart:io):
+  I/O for command-line apps.
+
+Except for dart:core, you must import a library before you can use it.
+Here's an example of importing dart:html, dart:math, and a
+third popular library called
+[polymer.dart](http://www.dartlang.org/polymer-dart/):
+
+    import 'dart:html';
+    import 'dart:math';
+    import 'package:polymer/polymer.dart';
+
+Polymer.dart is an example of a library that isn't
+included in the Dart download,
+but is easy to get and update using the _pub package manager_.
+For information on finding, using, and publishing libraries (and more)
+with pub, see
+[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)
+
+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).
+""";
+
 // 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.
 ///
 /// Used for lookup because of the dart2js mirrors exports
@@ skipping 72 matching lines @@
     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
       // "-" to separate the constructor from its name (if any).
       simpleName = '${mirrorOwner.simpleName}-$simpleName';
     }
     return getDocgenObject(mirrorOwner, owner).docName + '.' + simpleName;
   }
   List<Annotation> _createAnnotations(DeclarationMirror mirror,
-      MirrorBased owner) => null;
+      Library owningLibrary) => null;
 
   bool get isPrivate => mirror == null? false : mirror.isPrivate;
 }
 
 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,
-      MirrorBased owner) {
+      Library owningLibrary) {
     var annotationMirrors = mirror.metadata.where((e) =>
         e is dart2js.Dart2JsConstructedConstantMirror);
     var annotations = [];
     annotationMirrors.forEach((annotation) {
-      var docgenAnnotation = new Annotation(annotation, owner);
+      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 introduction: '',
+    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,
-      introduction: introduction, out: out, excludeLibraries: excludeLibraries,
+      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.
 
@@ skipping 24 matching lines @@
   /// [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.
   static Future<bool> generateDocumentation(List<String> files,
       {String packageRoot, bool outputToYaml: true, bool includePrivate: false,
        bool includeSdk: false, bool parseSdk: false, bool append: false,
-       String introduction: '', out: _DEFAULT_OUTPUT_DIRECTORY,
+       String introFileName: '', out: _DEFAULT_OUTPUT_DIRECTORY,
        List<String> excludeLibraries : const [],
        bool includeDependentPackages: false}) {
     _excluded = excludeLibraries;
     _includePrivate = includePrivate;
     logger.onRecord.listen((record) => print(record.message));
 
     _ensureOutputDirectory(out, append);
     var updatedPackageRoot = _obtainPackageRoot(packageRoot, parseSdk, files);
 
     var requestedLibraries = _findLibrariesToDocument(files,
@@ skipping 19 matching lines @@
             availableLibraries);
         var librariesToDocument = requestedLibraries.map(
             (each) => availableLibrariesByPath.putIfAbsent(each,
                 () => throw "Missing library $each")).toList();
         librariesToDocument.addAll(
             (includeSdk || parseSdk) ? Indexable._sdkLibraries : []);
         librariesToDocument.removeWhere(
             (x) => _excluded.contains(x.simpleName));
         _documentLibraries(librariesToDocument, includeSdk: includeSdk,
             outputToYaml: outputToYaml, append: append, parseSdk: parseSdk,
-            introduction: introduction);
+            introFileName: introFileName);
         return true;
       });
   }
 
   /// 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();
@@ skipping 12 matching lines @@
       }
     }
     File file = new File(path.join(_outputDirectory, filename));
     file.writeAsStringSync(text,
         mode: append ? FileMode.APPEND : FileMode.WRITE);
   }
 
   /// Creates documentation for filtered libraries.
   static void _documentLibraries(List<LibraryMirror> libs,
       {bool includeSdk: false, bool outputToYaml: true, bool append: false,
-       bool parseSdk: false, String introduction: ''}) {
+       bool parseSdk: false, String introFileName: ''}) {
     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.name] = library;
       }
     });
 
     var filteredEntities = entityMap.values.where(_isFullChainVisible);
 
@@ skipping 14 matching lines @@
     var aResult = set2.difference(set1);
     for (MirrorBased r in aResult) {
       print('     a result is $r and ${r.docName}');
     }*/
     //print(set1.difference(set2));
 
     // 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;
     var linkResolver = (name) => Indexable.globalFixReference(name);
+
+    String readIntroductionFile(String fileName, includeSdk) {
+      var defaultText = includeSdk ? DEFAULT_SDK_INTRODUCTION : '';
+      var introText = defaultText;
+      if (fileName.isNotEmpty) {
+        var introFile = new File(fileName);
+        introText = introFile.existsSync() ? introFile.readAsStringSync() :
+            defaultText;
+      }
+      return markdown.markdownToHtml(introText,
+          linkResolver: linkResolver, inlineSyntaxes: _MARKDOWN_SYNTAXES);
+    }
+
     if (append) {
       var docsDir = listDir(_outputDirectory);
       if (!docsDir.contains('$_outputDirectory/library_list.json')) {
         throw new StateError('No library_list.json');
       }
       libraryMap =
           JSON.decode(new File(
               '$_outputDirectory/library_list.json').readAsStringSync());
       libraryMap['libraries'].addAll(filteredEntities
           .where((e) => e is Library)
           .map((e) => e.previewMap));
-      if (introduction.isNotEmpty) {
-        var intro = libraryMap['introduction'];
-        if (intro.isNotEmpty) intro += '<br/><br/>';
-        intro += markdown.markdownToHtml(
-            new File(introduction).readAsStringSync(),
-                linkResolver: linkResolver, inlineSyntaxes: _MARKDOWN_SYNTAXES);
-        libraryMap['introduction'] = intro;
-      }
+      var intro = libraryMap['introduction'];
+      var spacing = intro.isEmpty ? '' : '<br/><br/>';
+      libraryMap['introduction'] =
+          "$intro$spacing${readIntroductionFile(introFileName, includeSdk)}";
       outputToYaml = libraryMap['filetype'] == 'yaml';
     } else {
       libraryMap = {
         'libraries' : filteredEntities.where((e) =>
             e is Library).map((e) => e.previewMap).toList(),
-        'introduction' : introduction == '' ?
-            '' : markdown.markdownToHtml(new File(introduction)
-                .readAsStringSync(), linkResolver: linkResolver,
-                    inlineSyntaxes: _MARKDOWN_SYNTAXES),
+        'introduction' : readIntroductionFile(introFileName, includeSdk),
         'filetype' : outputToYaml ? 'yaml' : 'json'
       };
     }
     _writeToFile(JSON.encode(libraryMap), 'library_list.json');
 
     // Output libraries and classes to file after all information is generated.
     filteredEntities.where((e) => e is Class || e is Library).forEach((output) {
       _writeIndexableToFile(output, outputToYaml);
     });
 
@@ skipping 78 matching lines @@
   /// For this run of docgen, determine the packageRoot value.
   ///
   /// If packageRoot is not explicitly passed, we examine the files we're
   /// documenting to attempt to find a package root.
   static String _obtainPackageRoot(String packageRoot, bool parseSdk,
       List<String> files) {
     if (packageRoot == null && !parseSdk) {
       // TODO(efortuna): This logic seems not very robust, but it's from the
       // original version of the code, pre-refactor, so I'm leavingt it for now.
       // Revisit to make more robust.
+      // TODO(efortuna): See lines 303-311 in
+      // https://codereview.chromium.org/116043013/diff/390001/pkg/docgen/lib/docgen.dart
       var type = FileSystemEntity.typeSync(files.first);
       if (type == FileSystemEntityType.DIRECTORY) {
         var files2 = listDir(files.first, recursive: true);
         // Return '' means that there was no pubspec.yaml and therefor no p
         // ackageRoot.
         packageRoot = files2.firstWhere((f) =>
             f.endsWith('${path.separator}pubspec.yaml'), orElse: () => '');
         if (packageRoot != '') {
           packageRoot = path.join(path.dirname(packageRoot), 'packages');
         }
       } else if (type == FileSystemEntityType.FILE) {
         logger.warning('WARNING: No package root defined. If Docgen fails, try '
             'again by setting the --package-root option.');
       }
      }
     logger.info('Package Root: ${packageRoot}');
-    return packageRoot;
+    return path.normalize(path.absolute(packageRoot));
   }
 
   /// Given the user provided list of items to document, expand all directories
   /// to document out into specific files and add any dependent packages for
   /// documentation if desired.
   static List<Uri> _findLibrariesToDocument(List<String> args,
       bool includeDependentPackages) {
     if (includeDependentPackages) {
       args.addAll(_allDependentPackageDirs(args.first));
     }
@@ skipping 118 matching lines @@
     if (map == null) map = new Map<String, Set<MirrorBased>>();
 
     var set = map[owner.docName];
     if (set == null) set = new Set<MirrorBased>();
     set.add(this);
     map[owner.docName] = set;
     mirrorToDocgen[this.mirror.qualifiedName] = map;
   }
 
   /** Walk up the owner chain to find the owning library. */
-  Library _getOwningLibrary(Indexable owner) {
-    if (owner is Library) return owner;
+  Library _getOwningLibrary(Indexable indexable) {
+    if (indexable is Library) return indexable;
     // TODO: is this needed?
-    if (owner is DummyMirror) return getDocgenObject(owner.mirror.library);
-    return _getOwningLibrary(owner.owner);
+    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')));
   }
 
   markdown.Node fixReferenceWithScope(String name) => null;
@@ skipping 173 matching lines @@
         var method = new Method(mirror, owner);
         entityMap[method.docName] = method;
         group[mirror.simpleName] = method;
       }
     });
     return group;
   }
 
   /// Returns a map of [Parameter] objects constructed from [mirrorList].
   Map<String, Parameter> _createParameters(List<ParameterMirror> mirrorList,
-      [Indexable owner]) {
+      Indexable owner) {
     var data = {};
     mirrorList.forEach((ParameterMirror mirror) {
-      data[mirror.simpleName] = new Parameter(mirror, owner);
+      data[mirror.simpleName] = new Parameter(mirror, _getOwningLibrary(owner));
     });
     return data;
   }
 
   /// Returns a map of [Generic] objects constructed from the class mirror.
   Map<String, Generic> _createGenerics(ClassMirror mirror) {
     return new Map.fromIterable(mirror.typeVariables,
         key: (e) => e.toString(),
         value: (e) => new Generic(e));
   }
@@ skipping 486 matching lines @@
     // 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();
     variables = _createVariables(classMirror.variables, this);
     methods = _createMethods(classMirror.methods, this);
-    annotations = _createAnnotations(classMirror, this);
+    annotations = _createAnnotations(classMirror, _getOwningLibrary(owner));
     generics = _createGenerics(classMirror);
     isAbstract = classMirror.isAbstract;
     inheritedMethods = new Map<String, Method>();
 
     // Tell all superclasses that you are a subclass, unless you are not
     // visible or an intermediary mixin class.
     if (!classMirror.isNameSynthetic && _isVisible) {
       parentChain().forEach((parentClass) {
           parentClass.addSubclass(this);
       });
@@ skipping 175 matching lines @@
     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;
     generics = _createGenerics(mirror);
-    parameters = _createParameters(mirror.value.parameters);
-    annotations = _createAnnotations(mirror, this);
+    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)
@@ skipping 97 matching lines @@
   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,
+  factory Method(MethodMirror mirror, Indexable owner, // Indexable newOwner.
       [Method methodInheritedFrom]) {
     var method = getDocgenObject(mirror, owner);
     if (method is DummyMirror) {
       method = new Method._(mirror, owner, methodInheritedFrom);
     }
     return method;
   }
 
   Method._(MethodMirror mirror, this.owner, this.methodInheritedFrom)
       : super(mirror) {
@@ skipping 50 matching lines @@
     return super.docName;
   }
 
   /// Makes sure that the method with an inherited equivalent have comments.
   void ensureCommentFor(Method inheritedMethod) {
     if (comment.isNotEmpty) return;
 
     comment = inheritedMethod._commentToHtml(this);
     _unresolvedComment = inheritedMethod._unresolvedComment;
     commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ?
-        inheritedMethod.qualifiedName : inheritedMethod.commentInheritedFrom;
+        inheritedMethod.mirror.qualifiedName :
+        inheritedMethod.commentInheritedFrom;
   }
 
   /// Generates a map describing the [Method] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'commentFrom': (methodInheritedFrom != null &&
         commentInheritedFrom == methodInheritedFrom.docName ? ''
         : commentInheritedFrom),
@@ skipping 20 matching lines @@
     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;
-      //print('result was $comment');
     }
     return result;
   }
 }
 
-/// A class containing properties of a Dart method/function parameter.
+/// 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;
   Type type;
   String defaultValue;
-
   /// List of the meta annotations on the parameter.
   List<Annotation> annotations;
 
-  Parameter(this.mirror, [Indexable owner]) {
+  Parameter(this.mirror, Library owningLibrary) {
     name = mirror.simpleName;
     isOptional = mirror.isOptional;
     isNamed = mirror.isNamed;
     hasDefaultValue = mirror.hasDefaultValue;
     defaultValue = mirror.defaultValue;
-    type = new Type(mirror.type, owner);
-    annotations = _createAnnotations(mirror, this);
+    type = new Type(mirror.type, owningLibrary);
+    annotations = _createAnnotations(mirror, owningLibrary);
   }
 
   /// Generates a map describing the [Parameter] object.
   Map toMap() => {
     'name': name,
     'optional': isOptional.toString(),
     'named': isNamed.toString(),
     'default': hasDefaultValue.toString(),
     'type': new List.filled(1, type.toMap()),
     'value': defaultValue,
     'annotations': annotations.map((a) => a.toMap()).toList()
   };
 }
 
 /// A Docgen wrapper around the dart2js mirror for a generic type.
 class Generic extends MirrorBased {
   TypeVariableMirror mirror;
   Generic(this.mirror);
   Map toMap() => {
     'name': mirror.toString(),
     'type': mirror.upperBound.qualifiedName
   };
 }
 
-/// Holds the name of a return type, and its generic type parameters.
+/// Docgen wrapper around the mirror for a return type, and/or 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" :
 ///
 ///        Map<String, List<int>>
 ///          "return" :
 ///            - "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 owner;
+  MirrorBased owningLibrary;
 
-  factory Type(TypeMirror mirror, [MirrorBased owner]) {
-    return new Type._(mirror, owner);
-  }
-
-  Type._(this.mirror, this.owner);
+  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, owner));
+        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 the owner at the last moment.
-    var result = getDocgenObject(mirror, owner);
+    // processed yet, so look up with the owningLibrary at the last moment.
+    var result = getDocgenObject(mirror, owningLibrary);
     return {
       'outer': 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, MirrorBased annotationOwner) {
+  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();
-    owner = annotationOwner;
   }
 
   Map toMap() => {
-    'name': getDocgenObject(mirror, owner).docName,
+    'name': getDocgenObject(mirror, owningLibrary).docName,
     'parameters': parameters
   };
 }