pkg/docgen: refactoring and cleanup

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]
 ///
 /// This creates files called `docs/<library_name>.yaml` in your current
 /// working directory.
 library docgen;
 
 import 'dart:convert';
 import 'dart:io';
 import 'dart:async';
 
 import 'package:logging/logging.dart';
 import 'package:markdown/markdown.dart' as markdown;
 import 'package:path/path.dart' as path;
 import 'package:yaml/yaml.dart';
 
 import 'dart2yaml.dart';
 import 'src/io.dart';
+import 'src/mdn.dart';
+import 'src/models.dart';
+import 'src/utils.dart';
+
 import '../../../sdk/lib/_internal/compiler/compiler.dart' as api;
 import '../../../sdk/lib/_internal/compiler/implementation/filenames.dart';
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/dart2js_mirrors.dart'
     as dart2js_mirrors;
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/analyze.dart'
     as dart2js;
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/source_mirrors.dart';
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dart'
     as dart2js_util;
 import '../../../sdk/lib/_internal/compiler/implementation/source_file_provider.dart';
 import '../../../sdk/lib/_internal/libraries.dart';
 
 const _DEFAULT_OUTPUT_DIRECTORY = 'docs';
 
 /// 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 =
+final 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:
@@ skipping 153 matching lines @@
   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 {
-  /// The original dart2js mirror around which this object wraps.
-  DeclarationMirror get mirror;
-
-  /// Returns a list of meta annotations assocated with a mirror.
-  static List<Annotation> _createAnnotations(DeclarationMirror mirror,
-      Library owningLibrary) {
-    var annotationMirrors = mirror.metadata.where((e) =>
-        e is dart2js_mirrors.Dart2JsConstructedConstantMirror);
-    var annotations = [];
-    annotationMirrors.forEach((annotation) {
-      var docgenAnnotation = new Annotation(annotation, owningLibrary);
-      if (!_SKIPPED_ANNOTATIONS.contains(
-          dart2js_util.qualifiedNameOf(docgenAnnotation.mirror))) {
-        annotations.add(docgenAnnotation);
-      }
-    });
-    return annotations;
-  }
-}
-
 /// Top level documentation traversal and generation object.
 ///
 /// Yes, everything in this class is used statically so this technically doesn't
 /// need to be its own class, but it's grouped together for semantic separation
 /// from the other classes and functionality in this library.
 class _Generator {
   /// The directory where the output docs are generated.
   static String _outputDirectory;
 
   /// This is set from the command line arguments flag --include-private
@@ skipping 582 matching lines @@
           });
         }
       },
       onError: (e) {
         print('HttpServer: an error occured $e');
       });
     });
   }
 }
 
+/** Walk up the owner chain to find the owning library. */

[Emily Fortuna, 2014/03/06 22:05:38]

Consistency! Triple slashes are everywhere through this file!

[kevmoo, 2014/03/06 22:20:17]

Sticking with copy-paste the old style for this CL. Another CL to cleanup up
comments.

+Library _getOwningLibrary(Indexable indexable) {

[Emily Fortuna, 2014/03/06 22:05:38]

make static function instead of global?

[kevmoo, 2014/03/06 22:20:17]

If the static uses privates on the class or make usage more clear, sure.

Otherwise, having thing top-level make cross-class usage easier (don't need to
qualify) and it makes dependencies clear (_getOwningLibrary doesn't need
anything special from Indexable)

[Alan Knight, 2014/03/12 18:17:56]

Why static or global at all? Why not just have this as a getter or zero-arg
method on Indexable and Library?

Library get owningLibrary =>  owner.owningLibrary

Library get owningLibrary => this;

Also Home is an Indexable that won't have an owningLibrary and may have a null
owner. So you either need a null check or an implementation in Home as well.

[kevmoo, 2014/03/17 02:01:29]

Done.

+  if (indexable is Library) return indexable;
+  return _getOwningLibrary(indexable.owner);
+}
+
 /// 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.
 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;
 
+  final DeclarationMirror mirror;

[Alan Knight, 2014/03/12 18:17:56]

If we're re-formatting these to have their own lines, shouldn't they also have
comments?

[kevmoo, 2014/03/17 02:01:29]

Not sure what the docs should be. Reverting whitespace for now.

+
+  final bool isPrivate;
+
   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);
+  Indexable(DeclarationMirror mirror)
+      : this.mirror = mirror,
+        this.isPrivate = isHidden(mirror) {
 
     var map = _mirrorToDocgen[dart2js_util.qualifiedNameOf(this.mirror)];
     if (map == null) map = new Map<String, Set<Indexable>>();
 
     var set = map[owner.docName];
     if (set == null) set = new Set<Indexable>();
     set.add(this);
     map[owner.docName] = set;
     _mirrorToDocgen[dart2js_util.qualifiedNameOf(this.mirror)] = map;
   }
 
-  /** Walk up the owner chain to find the owning library. */
-  Library _getOwningLibrary(Indexable indexable) {
-    if (indexable is Library) return indexable;
-    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;
 
   /// 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);
   }
 
   /// Look for the specified name starting with the current member, and
   /// progressively working outward to the current library scope.
   String findElementInScope(String name) =>
       _findElementInScope(name, packagePrefix);
 
-  /// For a given name, determine if we need to resolve it as a qualified name
-  /// or a simple name in the source mirors.
-  static determineLookupFunc(name) => name.contains('.') ?
-      dart2js_util.lookupQualifiedInScope :
-        (mirror, name) => mirror.lookupInScope(name);
-
   /// The reference to this element based on where it is printed as a
   /// documentation file and also the unique URL to refer to this item.
   ///
   /// 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;
 
   /// The full docName of the owner element, appended with a '.' for this
   /// object's name to be appended.
@@ skipping 30 matching lines @@
   ///
   /// "Owning" is defined as the object one scope-level above which this item
   /// is defined. Ex: The owner for a top level class, would be its enclosing
   /// library. The owner of a local variable in a method would be the enclosing
   /// method.
   Indexable get owner => new DummyMirror(mirror.owner);
 
   /// Generates MDN comments from database.json.
   String _mdnComment();
 
-  /// Generates the MDN Comment for variables and method DOM elements.
-  String _mdnMemberComment(String type, String member) {
-    var mdnType = _mdn[type];
-    if (mdnType == null) return '';
-    var mdnMember = mdnType['members'].firstWhere((e) => e['name'] == member,
-        orElse: () => null);
-    if (mdnMember == null) return '';
-    if (mdnMember['help'] == null || mdnMember['help'] == '') return '';
-    if (mdnMember['url'] == null) return '';
-    return _htmlifyMdn(mdnMember['help'], mdnMember['url']);
-  }
-
-  /// Generates the MDN Comment for class DOM elements.
-  String _mdnTypeComment(String type) {
-    var mdnType = _mdn[type];
-    if (mdnType == null) return '';
-    if (mdnType['summary'] == null || mdnType['summary'] == "") return '';
-    if (mdnType['srcUrl'] == null) return '';
-    return _htmlifyMdn(mdnType['summary'], mdnType['srcUrl']);
-  }
-
-  /// Encloses the given content in an MDN div and the original source link.
-  String _htmlifyMdn(String content, String url) {
-    return '<div class="mdn">' + content.trim() + '<p class="mdn-note">'
-        '<a href="' + url.trim() + '">from Mdn</a></p></div>';
-  }
-
   /// 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' : name, 'qualifiedName' : qualifiedName };
     var preview = _preview;
     if(preview != null) finalMap['preview'] = preview;
     return finalMap;
   }
@@ skipping 48 matching lines @@
   /// Returns a map of [Variable] objects constructed from [mirrorMap].
   /// The optional parameter [containingLibrary] is contains data for variables
   /// defined at the top level of a library (potentially for exporting
   /// purposes).
   Map<String, Variable> _createVariables(Iterable<VariableMirror> mirrors,
       Indexable owner) {
     var data = {};
     // TODO(janicejl): When map to map feature is created, replace the below
     // with a filter. Issue(#9590).
     mirrors.forEach((VariableMirror mirror) {
-      if (_Generator._includePrivate || !_isHidden(mirror)) {
+      if (_Generator._includePrivate || !isHidden(mirror)) {
         var mirrorName = dart2js_util.nameOf(mirror);
         data[mirrorName] = new Variable(mirrorName, mirror, owner);
       }
     });
     return data;
   }
 
   /// Returns a map of [Method] objects constructed from [mirrorMap].
   /// The optional parameter [containingLibrary] is contains data for variables
   /// defined at the top level of a library (potentially for exporting
@@ skipping 26 matching lines @@
         key: (e) => dart2js_util.nameOf(e),
         value: (e) => new Generic(e));
   }
 
   /// Return an informative [Object.toString] for debugging.
   String toString() => "${super.toString()}(${name.toString()})";
 
   /// Return a map representation of this type.
   Map toMap();
 
-  /// A declaration is private if itself is private, or the owner is private.
-  // Issue(12202) - A declaration is public even if it's owner is private.
-  bool _isHidden(DeclarationMirror mirror) {
-    if (mirror is LibraryMirror) {
-      return _isLibraryPrivate(mirror);
-    } else if (mirror.owner is LibraryMirror) {
-      return (mirror.isPrivate || _isLibraryPrivate(mirror.owner)
-          || mirror.isNameSynthetic);
-    } else {
-      return (mirror.isPrivate || _isHidden(mirror.owner)
-          || owner.mirror.isNameSynthetic);
-    }
-  }
 
-  /// 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
-  bool _isLibraryPrivate(LibraryMirror mirror) {
-    // This method is needed because LibraryMirror.isPrivate returns `false` all
-    // the time.
-    var sdkLibrary = LIBRARIES[dart2js_util.nameOf(mirror)];
-    if (sdkLibrary != null) {
-      return !sdkLibrary.documented;
-    } else if (dart2js_util.nameOf(mirror).startsWith('_') ||
-        dart2js_util.nameOf(mirror).contains('._')) {
-      return true;
-    }
-    return false;
-  }
 
   ////// Top level resolution functions
   /// Converts all [foo] references in comments to <a>libraryName.foo</a>.
   static markdown.Node globalFixReference(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);
   }
 
   /// This is a more complex reference. Try to break up if its of the form A<B>
   /// where A is an alphanumeric string and B is an A, a list of B ("B, B, B"),
   /// or of the form A<B>. Note: unlike other the other markdown-style links,
   /// all text inside the square brackets is treated as part of the link (aka
   /// the * is interpreted literally as a *, not as a indicator for bold <em>.
   ///
   /// Example: [foo&lt;_bar_>] will produce
   /// <a>resolvedFoo</a>&lt;<a>resolved_bar_</a>> rather than an italicized
   /// version of resolvedBar.
   static markdown.Node _fixComplexReference(String name) {
     // Parse into multiple elements we can try to resolve.
-    var tokens = _tokenizeComplexReference(name);
+    var tokens = tokenizeComplexReference(name);
 
     // Produce an html representation of our elements. Group unresolved and
     // plain text are grouped into "link" elements so they display as code.
-    final textElements = [' ', ',', '>', _LESS_THAN];
+    final textElements = [' ', ',', '>', LESS_THAN];
     var accumulatedHtml = '';
 
     for (var token in tokens) {
       bool added = false;
       if (!textElements.contains(token)) {
         String elementName = _findElementInScope(token, '');
         if (elementName != null) {
           accumulatedHtml += markdown.renderToHtml([new markdown.Element.text(
               'a', elementName)]);
           added = true;
         }
       }
       if (!added) {
         accumulatedHtml += token;
        }
      }
     return new markdown.Text(accumulatedHtml);
   }
 
-
-  // HTML escaped version of '<' character.
-  static final _LESS_THAN = '&lt;';
-
-  /// Chunk the provided name into individual parts to be resolved. We take a
-  /// simplistic approach to chunking, though, we break at " ", ",", "&lt;"
-  /// and ">". All other characters are grouped into the name to be resolved.
-  /// As a result, these characters will all be treated as part of the item to
-  /// be resolved (aka the * is interpreted literally as a *, not as an
-  /// indicator for bold <em>.
-  static List<String> _tokenizeComplexReference(String name) {
-    var tokens = [];
-    var append = false;
-    var index = 0;
-    while(index < name.length) {
-      if (name.indexOf(_LESS_THAN, index) == index) {
-        tokens.add(_LESS_THAN);
-        append = false;
-        index += _LESS_THAN.length;
-      } else if (name[index] == ' ' || name[index] == ',' ||
-          name[index] == '>') {
-        tokens.add(name[index]);
-        append = false;
-        index++;
-      } else {
-        if (append) {
-          tokens[tokens.length - 1] = tokens.last + name[index];
-        } else {
-          tokens.add(name[index]);
-          append = true;
-        }
-        index++;
-      }
-    }
-    return tokens;
-  }
-
   static String _findElementInScope(String name, String packagePrefix) {
     var lookupFunc = determineLookupFunc(name);
     // Look in the dart core library scope.
     var coreScope = _coreLibrary == null? null :
         lookupFunc(_coreLibrary.mirror, name);
     if (coreScope != null) return packagePrefix + _coreLibrary.docName;
 
     // If it's a reference that starts with a another library name, then it
     // looks for a match of that library name in the other sdk libraries.
     if(name.contains('.')) {
@@ skipping 15 matching lines @@
           }
         }
       }
      }
     return null;
   }
 
   /// Expand the method map [mapToExpand] into a more detailed map that
   /// separates out setters, getters, constructors, operators, and methods.
   Map _expandMethodMap(Map<String, Method> mapToExpand) => {
-    'setters': recurseMap(_filterMap(mapToExpand,
+    'setters': recurseMap(filterMap(mapToExpand,
         (key, val) => val.mirror.isSetter)),
-    'getters': recurseMap(_filterMap(mapToExpand,
+    'getters': recurseMap(filterMap(mapToExpand,
         (key, val) => val.mirror.isGetter)),
-    'constructors': recurseMap(_filterMap(mapToExpand,
+    'constructors': recurseMap(filterMap(mapToExpand,
         (key, val) => val.mirror.isConstructor)),
-    'operators': recurseMap(_filterMap(mapToExpand,
+    'operators': recurseMap(filterMap(mapToExpand,
         (key, val) => val.mirror.isOperator)),
-    'methods': recurseMap(_filterMap(mapToExpand,
+    'methods': recurseMap(filterMap(mapToExpand,
         (key, val) => val.mirror.isRegularMethod && !val.mirror.isOperator))
   };
 
-  /// 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;
-  }
-
-  Map _filterMap(Map map, Function test) {
-    var exported = new Map();
-    map.forEach((key, value) {
-      if (test(key, value)) exported[key] = value;
-    });
-    return exported;
-  }
-
   /// Accessor to determine if this item and all of its owners are visible.
   bool get _isVisible => _Generator._isFullChainVisible(this);
 
   /// 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.
@@ skipping 97 matching lines @@
     this.functions = _createMethods(_addAll(exported['methods'],
         libraryMirror.declarations.values.where(
             (mirror) => mirror is MethodMirror)).values, this);
     this.variables = _createVariables(_addAll(exported['variables'],
         dart2js_util.variablesOf(libraryMirror.declarations)).values, 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 lookupFunc = determineLookupFunc(name);
     var libraryScope = lookupFunc(mirror, name);
     if (libraryScope != null) {
       var result = Indexable.getDocgenObject(libraryScope, this);
       if (result is DummyMirror) return packagePrefix + result.docName;
       return result.packagePrefix + result.docName;
     }
     return super.findElementInScope(name);
   }
 
   String _mdnComment() => '';
@@ skipping 120 matching lines @@
   /// corresponding to the actual DeclarationMirror.
   Map<String, Map<String, DeclarationMirror>> _calcExportedItems(
       LibrarySourceMirror library) {
     var exports = {};
     exports['classes'] = {};
     exports['methods'] = {};
     exports['variables'] = {};
 
     // Determine the classes, variables and methods that are exported for a
     // specific dependency.
-    _populateExports(LibraryDependencyMirror export, bool showExport) {
+    void _populateExports(LibraryDependencyMirror export, bool showExport) {
       if (!showExport) {
         // Add all items, and then remove the hidden ones.
         // Ex: "export foo hide bar"
         _addAll(exports['classes'],
             dart2js_util.typesOf(export.targetLibrary.declarations));
         _addAll(exports['methods'],
             export.targetLibrary.declarations.values.where(
                 (mirror) => mirror is MethodMirror));
         _addAll(exports['variables'],
             dart2js_util.variablesOf(export.targetLibrary.declarations));
@@ skipping 77 matching lines @@
 
   /// 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 + '.' + dart2js_util.nameOf(mirror);
 
   OwnedIndexable(DeclarationMirror mirror, this.owner) : super(mirror);
 
   /// Generates MDN comments from database.json.
   String _mdnComment() {
-    //Check if MDN is loaded.
-    if (Indexable._mdn == null) {
-      // Reading in MDN related json file.
-      var root = _Generator._rootDirectory;
-      var mdnPath = path.join(root, 'utils/apidoc/mdn/database.json');
-      var mdnFile = new File(mdnPath);
-      if (mdnFile.existsSync()) {
-        Indexable._mdn = JSON.decode(mdnFile.readAsStringSync());
-      } else {
-        _Generator.logger.warning("Cannot find MDN docs expected at $mdnPath");
-        Indexable._mdn = {};
-      }
-    }
     var domAnnotation = this.annotations.firstWhere(
         (e) => e.mirror.qualifiedName == #metadata.DomName,
         orElse: () => null);
     if (domAnnotation == null) return '';
     var domName = domAnnotation.parameters.single;
-    var parts = domName.split('.');
-    if (parts.length == 2) return _mdnMemberComment(parts[0], parts[1]);
-    if (parts.length == 1) return _mdnTypeComment(parts[0]);
 
-    throw new StateError('More than two items is not supported: $parts');
+    return mdnComment(_Generator._rootDirectory, _Generator.logger, domName);
   }
 
   String get packagePrefix => owner.packagePrefix;
 }
 
 /// A class containing contents of a Dart class.
 class Class extends OwnedIndexable implements Comparable {
 
   /// List of the names of interfaces that this class implements.
   List<Class> interfaces = [];
@@ skipping 58 matching lines @@
     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(
         dart2js_util.variablesOf(classMirror.declarations), this);
     methods = _createMethods(classMirror.declarations.values.where(
         (mirror) => mirror is MethodMirror), this);
-    annotations = MirrorBased._createAnnotations(classMirror, _getOwningLibrary(owner));
+    annotations = _createAnnotations(classMirror, _getOwningLibrary(owner));
     generics = _createGenerics(classMirror);
     isAbstract = classMirror.isAbstract;
     inheritedMethods = new Map<String, Method>();
 
     // Tell superclass that you are a subclass, unless you are not
     // visible or an intermediary mixin class.
     if (!classMirror.isNameSynthetic && _isVisible && superclass != null) {
       superclass.addSubclass(this);
     }
 
     if (this.superclass != null) addInherited(superclass);
     interfaces.forEach((interface) => addInherited(interface));
   }
 
   String _lookupInClassAndSuperclasses(String name) {
-    var lookupFunc = Indexable.determineLookupFunc(name);
+    var lookupFunc = determineLookupFunc(name);
     var classScope = this;
     while (classScope != null) {
       var classFunc = lookupFunc(classScope.mirror, name);
       if (classFunc != null) {
         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);
+    var lookupFunc = determineLookupFunc(name);
     var result = _lookupInClassAndSuperclasses(name);
     if (result != null) {
       return result;
     }
     result = owner.findElementInScope(name);
     return result == null ? super.findElementInScope(name) : result;
   }
 
   String get typeName => 'class';
 
@@ skipping 131 matching lines @@
       aTypedef = new Typedef._(mirror, owningLibrary);
     }
     return aTypedef;
   }
 
   Typedef._(TypedefMirror mirror, Library owningLibrary) :
       super(mirror, owningLibrary) {
     returnType = Indexable.getDocgenObject(mirror.referent.returnType).docName;
     generics = _createGenerics(mirror);
     parameters = _createParameters(mirror.referent.parameters, owningLibrary);
-    annotations = MirrorBased._createAnnotations(mirror, owningLibrary);
+    annotations = _createAnnotations(mirror, owningLibrary);

[Emily Fortuna, 2014/03/06 22:05:38]

is having a bunch of random global functions really better? I'm not certain.

[kevmoo, 2014/03/06 22:20:17]

Random top-level methods make dependencies clear. Not using something special or
private to a given class IMHO

[Alan Knight, 2014/03/12 18:17:56]

I don't think it's about strict dependency requirements. This is only ever used
in the construction of a MirrorBased. Having it as a top-level function makes it
top-level noise when it's really an internal detail of MirrorBased. It would be
better as an instance method but I presume it can't be because it's called in
the constructor.

[kevmoo, 2014/03/17 02:01:29]

Since MirrorBased is in another library and we want this private, the only
option is for it to be top-level.

If at some point the rest of the types get into the models lib, we can go back
to the static method model

   }
 
   Map toMap() {
     var map = {
       'name': name,
       'qualifiedName': qualifiedName,
       'comment': comment,
       'return': returnType,
       'parameters': recurseMap(parameters),
       'annotations': annotations.map((a) => a.toMap()).toList(),
@@ skipping 32 matching lines @@
     }
     return variable;
   }
 
   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 = MirrorBased._createAnnotations(mirror, _getOwningLibrary(owner));
+    annotations = _createAnnotations(mirror, _getOwningLibrary(owner));
   }
 
   String get name => _variableName;
 
   /// Generates a map describing the [Variable] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'final': isFinal,
     'static': isStatic,
     'constant': isConst,
     'type': new List.filled(1, type.toMap()),
     'annotations': annotations.map((a) => a.toMap()).toList()
   };
 
   String get typeName => 'property';
 
   get comment {
     if (_comment != null) return _comment;
     if (owner is Class) {
       (owner as Class).ensureComments();
     }
     return super.comment;
   }
 
   String findElementInScope(String name) {
-    var lookupFunc = Indexable.determineLookupFunc(name);
+    var lookupFunc = determineLookupFunc(name);
     var result = lookupFunc(mirror, name);
     if (result != null) {
       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) {
@@ skipping 30 matching lines @@
     return method;
   }
 
   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 = MirrorBased._createAnnotations(mirror, _getOwningLibrary(owner));
+    annotations = _createAnnotations(mirror, _getOwningLibrary(owner));
   }
 
   Method get originallyInheritedFrom => methodInheritedFrom == null ?
       this : methodInheritedFrom.originallyInheritedFrom;
 
   /// 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 lookupFunc = 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 = Indexable.getDocgenObject(memberScope, owner);
       if (result is DummyMirror && owner.owner != null
           && owner.owner is! DummyMirror) {
         var aresult = Indexable.getDocgenObject(memberScope, owner.owner);
@@ skipping 99 matching lines @@
   final List<Annotation> annotations;
 
   Parameter(ParameterMirror mirror, Library owningLibrary)
       : this.mirror = mirror,
         name = dart2js_util.nameOf(mirror),
         isOptional = mirror.isOptional,
         isNamed = mirror.isNamed,
         hasDefaultValue = mirror.hasDefaultValue,
         defaultValue = '${mirror.defaultValue}',
         type = new Type(mirror.type, owningLibrary),
-        annotations = MirrorBased._createAnnotations(mirror, owningLibrary);
+        annotations = _createAnnotations(mirror, owningLibrary);
 
   /// Generates a map describing the [Parameter] object.
   Map toMap() => {
     'name': name,
     'optional': isOptional,
     'named': isNamed,
     'default': hasDefaultValue,
     '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 {
-  final TypeVariableMirror mirror;
-  Generic(this.mirror);
-  Map toMap() => {
-    'name': dart2js_util.nameOf(mirror),
-    'type': dart2js_util.qualifiedNameOf(mirror.upperBound)
-  };
-}
-
 /// 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"
@@ skipping 59 matching lines @@
         .map((e) => originalMirror.getField(e.simpleName).reflectee)
         .where((e) => e != null)
         .toList();
   }
 
   Map toMap() => {
     'name': Indexable.getDocgenObject(mirror, owningLibrary).docName,
     'parameters': parameters
   };
 }
+
+/// 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_mirrors.Dart2JsConstructedConstantMirror);
+  var annotations = [];
+  annotationMirrors.forEach((annotation) {
+    var docgenAnnotation = new Annotation(annotation, owningLibrary);
+    if (!_SKIPPED_ANNOTATIONS.contains(
+        dart2js_util.qualifiedNameOf(docgenAnnotation.mirror))) {
+      annotations.add(docgenAnnotation);
+    }
+  });
+  return annotations;
+}