Additional refactoring for docgen.

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 78 matching lines @@
   * [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/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>();
-
 /// 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.
@@ skipping 67 matching lines @@
   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.
   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;
   }
 }
 
+/// Top level documentation traversal and generation object.
+///
+/// Yes, everything in this class is used statically so this technically need

[Alan Knight, 2014/01/31 17:48:53]

missing "doesn't" ?

[Emily Fortuna, 2014/02/01 02:06:48]

Done

+/// 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 var _outputDirectory;
 
   /// This is set from the command line arguments flag --include-private
   static bool _includePrivate = false;
 
   /// Library names to explicitly exclude.
   ///
   ///   Set from the command line option
   /// --exclude-lib.
   static List<String> _excluded;
 
+  /// Logger for printing out progress of documentation generation.
   static Logger logger = new Logger('Docgen');
 
   /// 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.
@@ skipping 19 matching lines @@
     if (includeSdk) {
       allLibraries.addAll(_listSdk());
     }
 
     return getMirrorSystem(allLibraries, packageRoot: updatedPackageRoot,
         parseSdk: parseSdk)
       .then((MirrorSystem mirrorSystem) {
         if (mirrorSystem.libraries.isEmpty) {
           throw new StateError('No library mirrors were created.');
         }
-        Indexable.initializeTopLevelLibraries(mirrorSystem);
+        Indexable._initializeTopLevelLibraries(mirrorSystem);
 
         var availableLibraries = mirrorSystem.libraries.values.where(
             (each) => each.uri.scheme == 'file');
         var availableLibrariesByPath = new Map.fromIterables(
             availableLibraries.map((each) => each.uri),
             availableLibraries);
         var librariesToDocument = requestedLibraries.map(
             (each) => availableLibrariesByPath.putIfAbsent(each,
                 () => throw "Missing library $each")).toList();
         librariesToDocument.addAll(
@@ skipping 25 matching lines @@
         if (!subdir.existsSync()) {
           subdir.createSync();
         }
       }
     }
     File file = new File(path.join(_outputDirectory, filename));
     file.writeAsStringSync(text,
         mode: append ? FileMode.APPEND : FileMode.WRITE);
   }
 
+  /// Resolve all the links in the introductory comments for a given library or
+  /// package as specified by [filename].
+  static String _readIntroductionFile(String fileName, bool includeSdk) {
+    var linkResolver = (name) => Indexable.globalFixReference(name);
+    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);
+  }
+
   /// Creates documentation for filtered libraries.
   static void _documentLibraries(List<LibraryMirror> libs,
       {bool includeSdk: false, bool outputToYaml: true, bool append: false,
        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);
-
-    /*var filteredEntities2 = new Set<MirrorBased>();
-    for (Map<String, Set<MirrorBased>> firstLevel in mirrorToDocgen.values) {
-      for (Set<MirrorBased> items in firstLevel.values) {
-        for (MirrorBased item in items) {
+    var filteredEntities = new Set<Indexable>();
+    for (Map<String, Set<Indexable>> firstLevel in
+        Indexable._mirrorToDocgen.values) {
+      for (Set<Indexable> items in firstLevel.values) {
+        for (Indexable item in items) {
           if (_isFullChainVisible(item)) {
-            filteredEntities2.add(item);
+            if (item is! Method ||
+                (item is Method && item.methodInheritedFrom == null)) {
+              filteredEntities.add(item);
+            }
           }
         }
       }
-    }*/
-
-    /*print('THHHHHEEE DIFFERENCE IS');
-    var set1 = new Set.from(filteredEntities);
-    var set2 = new Set.from(filteredEntities2);
-    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));
       var intro = libraryMap['introduction'];
       var spacing = intro.isEmpty ? '' : '<br/><br/>';
       libraryMap['introduction'] =
-          "$intro$spacing${readIntroductionFile(introFileName, includeSdk)}";
+          "$intro$spacing${_readIntroductionFile(introFileName, includeSdk)}";
       outputToYaml = libraryMap['filetype'] == 'yaml';
     } else {
       libraryMap = {
         'libraries' : filteredEntities.where((e) =>
             e is Library).map((e) => e.previewMap).toList(),
-        'introduction' : readIntroductionFile(introFileName, includeSdk),
+        'introduction' : _readIntroductionFile(introFileName, includeSdk),
         'filetype' : outputToYaml ? 'yaml' : 'json'
       };
     }
+    _writeOutputFiles(libraryMap, filteredEntities, outputToYaml, append);
+  }
+
+  /// Output all of the libraries and classes into json or yaml files for
+  /// consumption by a viewer.
+  static void _writeOutputFiles(libraryMap,
+      Iterable<Indexable> filteredEntities, bool outputToYaml, bool append) {
     _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);
     });
 
     // Outputs all the qualified names documented with their type.
     // This will help generate search results.
     _writeToFile(filteredEntities.map((e) =>
         '${e.qualifiedName} ${e.typeName}').join('\n') + '\n',
         'index.txt', append: append);
     var index = new Map.fromIterables(
         filteredEntities.map((e) => e.qualifiedName),
         filteredEntities.map((e) => e.typeName));
     if (append) {
       var previousIndex =
           JSON.decode(new File(
               '$_outputDirectory/index.json').readAsStringSync());
       index.addAll(previousIndex);
     }
     _writeToFile(JSON.encode(index), 'index.json');
   }
 
+  /// Helper method to serialize the given Indexable out to a file.
   static void _writeIndexableToFile(Indexable result, bool outputToYaml) {
     var outputFile = result.fileName;
     var output;
     if (outputToYaml) {
       output = getYamlString(result.toMap());
       outputFile = outputFile + '.yaml';
     } else {
       output = JSON.encode(result.toMap());
       outputFile = outputFile + '.json';
     }
     _writeToFile(output, outputFile);
   }
 
   /// Set the location of the ouput directory, and ensure that the location is
   /// available on the file system.
   static void _ensureOutputDirectory(String outputDirectory, bool append) {
     _outputDirectory = outputDirectory;
     if (!append) {
       var dir = new Directory(_outputDirectory);
       if (dir.existsSync()) dir.deleteSync(recursive: true);
      }
   }
 
-
+  /// Helper accessor to determine the full pathname of the root of the dart
+  /// checkout.
   static String get _rootDirectory {
     var scriptDir = path.absolute(path.dirname(Platform.script.toFilePath()));
     var root = scriptDir;
     while(path.basename(root) != 'dart') {
       root = path.dirname(root);
     }
     return root;
   }
 
   /// Analyzes set of libraries and provides a mirror system which can be used
@@ skipping 24 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');
         }
@@ skipping 73 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;
   }
 
+  /// Return true if this item and all of its owners are all visible.
   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 ?
+    return _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;
   }
 }
@@ skipping 51 matching lines @@
     map[owner.docName] = set;
     _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;
     return _getOwningLibrary(indexable.owner);
   }
 
-  static initializeTopLevelLibraries(MirrorSystem mirrorSystem) {
+  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);
   }
 
   /// 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 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 {
-    return packagePrefix + ownerPrefix + 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.
   String get ownerPrefix => owner.docName != '' ? owner.docName + '.' : '';
 
+  /// The prefix String to refer to the package that this item is in, for URLs
+  /// and comment resolution.
+  ///
+  /// The prefix can be prepended to a qualified name to get a fully unique
+  /// name among all packages.
   String get packagePrefix => '';
 
-  /// Documentation comment with converted markdown.
+  /// Documentation comment with converted markdown and all links resolved.
   String _comment;
 
+  /// Accessor to documentation comment with markdown converted to html and all
+  /// links resolved.
   String get comment {
     if (_comment != null) return _comment;
 
     _comment = _commentToHtml();
     if (_comment.isEmpty) {
       _comment = _mdnComment();
     }
     return _comment;
   }
 
   set comment(x) => _comment = x;
 
+  /// The simple name to refer to this item.
   String get name => mirror.simpleName;
 
+  /// Accessor to the parent item that owns this item.
+  ///
+  /// "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() {
-    //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());
-    }
-    // TODO: refactor OOP
-    if (this is Library) return '';
-    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]);
-  }
+  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 _htmlMdn(mdnMember['help'], mdnMember['url']);
+    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 _htmlMdn(mdnType['summary'], mdnType['srcUrl']);
+    return _htmlifyMdn(mdnType['summary'], mdnType['srcUrl']);
   }
 
-  String _htmlMdn(String content, String url) {
+  /// 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 };
     if (comment != '') {
       var index = comment.indexOf('</p>');
       finalMap['preview'] = '${comment.substring(0, index)}</p>';
     }
     return finalMap;
   }
 
-  String _getCommentText() {
+  /// Accessor to obtain the raw comment text for a given item, _without_ any
+  /// of the links resolved.
+  String get _commentText {
     String commentText;
     mirror.metadata.forEach((metadata) {
       if (metadata is CommentInstanceMirror) {
         CommentInstanceMirror comment = metadata;
         if (comment.isDocComment) {
           if (commentText == null) {
             commentText = comment.trimmedText;
           } else {
             commentText = '$commentText\n${comment.trimmedText}';
           }
         }
       }
     });
     return commentText;
   }
 
   /// Returns any documentation comments associated with a mirror with
   /// simple markdown converted to html.
   ///
   /// By default we resolve any comment references within our own scope.
   /// However, if a method is inherited, we want the inherited comments, but
   /// links to the subclasses's version of the methods.
   String _commentToHtml([Indexable resolvingScope]) {
     if (resolvingScope == null) resolvingScope = this;
-    var commentText = _getCommentText();
+    var commentText = _commentText;
     _unresolvedComment = commentText;
 
-    var linkResolver = (name) => resolvingScope.fixReferenceWithScope(name);
+    var linkResolver = (name) => resolvingScope.fixReference(name);
     commentText = commentText == null ? '' :
         markdown.markdownToHtml(commentText.trim(), linkResolver: linkResolver,
             inlineSyntaxes: _MARKDOWN_SYNTAXES);
     return commentText;
   }
 
   /// 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(Map<String, VariableMirror> mirrorMap,
       Indexable owner) {
     var data = {};
     // TODO(janicejl): When map to map feature is created, replace the below
     // with a filter. Issue(#9590).
     mirrorMap.forEach((String mirrorName, VariableMirror mirror) {
       if (_Generator._includePrivate || !_isHidden(mirror)) {
-        var variable = new Variable(mirrorName, mirror, owner);
-        entityMap[variable.docName] = variable;
-        data[mirrorName] = entityMap[variable.docName];
+        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
   /// purposes).
   Map<String, Method> _createMethods(Map<String, MethodMirror> mirrorMap,
       Indexable owner) {
     var group = new Map<String, Method>();
     mirrorMap.forEach((String mirrorName, MethodMirror mirror) {
       if (_Generator._includePrivate || !mirror.isPrivate) {
-        var method = new Method(mirror, owner);
-        entityMap[method.docName] = method;
-        group[mirror.simpleName] = method;
+        group[mirror.simpleName] = new Method(mirror, owner);
       }
     });
     return group;
   }
 
   /// Returns a map of [Parameter] objects constructed from [mirrorList].
   Map<String, Parameter> _createParameters(List<ParameterMirror> mirrorList,
       Indexable owner) {
     var data = {};
     mirrorList.forEach((ParameterMirror mirror) {
       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));
   }
 
   /// Return an informative [Object.toString] for debugging.
   String toString() => "${super.toString()}(${name.toString()})";
 
   /// Return a map representation of this type.
-  Map toMap() {}
-
+  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
-  // This is because LibraryMirror.isPrivate returns `false` all the time.
   bool _isLibraryPrivate(LibraryMirror mirror) {
+    // This method is needed because LibraryMirror.isPrivate returns `false` all
+    // the time.
     var sdkLibrary = LIBRARIES[mirror.simpleName];
     if (sdkLibrary != null) {
       return !sdkLibrary.documented;
     } else if (mirror.simpleName.startsWith('_') ||
         mirror.simpleName.contains('._')) {
       return true;
     }
     return false;
   }
 
@@ skipping 105 matching lines @@
             return packagePrefix + result.docName;
           } else {
             return result.packagePrefix + result.docName;
           }
         }
       }
      }
     return null;
   }
 
-  Map expandMethodMap(Map<String, Method> mapToExpand) => {
-    'setters': recurseMap(_filterMap(new Map(), mapToExpand,
+  /// 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,
         (key, val) => val.mirror.isSetter)),
-    'getters': recurseMap(_filterMap(new Map(), mapToExpand,
+    'getters': recurseMap(_filterMap(mapToExpand,
         (key, val) => val.mirror.isGetter)),
-    'constructors': recurseMap(_filterMap(new Map(), mapToExpand,
+    'constructors': recurseMap(_filterMap(mapToExpand,
         (key, val) => val.mirror.isConstructor)),
-    'operators': recurseMap(_filterMap(new Map(), mapToExpand,
+    'operators': recurseMap(_filterMap(mapToExpand,
         (key, val) => val.mirror.isOperator)),
-    'methods': recurseMap(_filterMap(new Map(), 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(exported, map, test) {
+  Map _filterMap(Map map, Function test) {
+    var exported = new Map();
     map.forEach((key, value) {
       if (test(key, value)) exported[key] = value;
     });
     return exported;
   }
 
-  bool get _isVisible => _Generator._includePrivate || !isPrivate;
+  /// 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.
   static Indexable getDocgenObject(DeclarationMirror mirror,
     [Indexable owner]) {
@@ skipping 25 matching lines @@
       }
     }
 
     if (results.length > 0) {
       // This might occur if we didn't specify an "owner."
       return results.first;
     }
     return new DummyMirror(mirror, owner);
   }
 
+  /// Returns true if [mirror] is the correct type of mirror that this Docgen
+  /// object wraps. (Workaround for the fact that Types are not first class.)
   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;
+  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 = 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) {
-            var aTypedef = new Typedef(mirror, this);
-            entityMap[Indexable.getDocgenObject(mirror).docName] = aTypedef;
-            typedefs[mirror.simpleName] = aTypedef;
+            typedefs[mirror.simpleName] = new Typedef(mirror, this);
           }
         } 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(
@@ skipping 13 matching lines @@
     var lookupFunc = Indexable.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() => '';
+
   /// 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 (_hasBeenCheckedForPackage) return packageName;
+    _hasBeenCheckedForPackage = true;
     if (mirror.uri.scheme != 'file') return '';
     // We assume that we are documenting only libraries under package/lib
     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(_getRootdir(mirror));
     return packageName;
   }
 
@@ skipping 24 matching lines @@
     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 ?
       '' : '$packageName/';
 
   Map get previewMap {
     var basic = super.previewMap;
     basic['packageName'] = packageName;
     if (packageIntro != null) {
       basic['packageIntro'] = packageIntro;
     }
     return basic;
@@ skipping 59 matching lines @@
       // library. Ex: "export foo show bar"
       // Otherwise, add all items, and then remove the hidden ones.
       // Ex: "export foo hide bar"
       _populateExports(export,
           export.combinators.any((combinator) => combinator.isShow));
     }
     return exports;
   }
 
   /// Checks if the given name is a key for any of the Class Maps.
-  bool containsKey(String name) {
-    return classes.containsKey(name) || errors.containsKey(name);
-  }
+  bool containsKey(String name) =>
+      classes.containsKey(name) || errors.containsKey(name);
 
   /// Generates a map describing the [Library] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'variables': recurseMap(variables),
-    'functions': expandMethodMap(functions),
+    'functions': _expandMethodMap(functions),
     'classes': {
       'class': classes.values.where((c) => c._isVisible)
         .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 {
+  /// 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 owner;
 
+  /// List of the meta annotations on this item.
+  List<Annotation> annotations;
+
   /// 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);
+
+  /// 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');
+      Indexable._mdn = JSON.decode(new File(mdnPath).readAsStringSync());
+    }
+    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]);
+  }
 }
 
 /// 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 = [];
 
   /// 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;
 
   /// Inherited variables in the class.
   Map<String, Variable> inheritedVariables;
 
   /// Methods in the class.
   Map<String, Method> methods;
 
   Map<String, Method> inheritedMethods;
 
   /// Generic infomation about the class.
   Map<String, Generic> generics;
 
   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;
 
   /// Returns the [Class] for the given [mirror] if it has already been created,
   /// else creates it.
   factory Class(ClassMirror mirror, Library 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) {
@@ skipping 21 matching lines @@
         new Class._possiblyDifferentOwner(classMirror.superclass, owner);
 
     interfaces = superinterfaces.toList();
     variables = _createVariables(classMirror.variables, this);
     methods = _createMethods(classMirror.methods, 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
+    // Tell superclass 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);
-      });
+    if (!classMirror.isNameSynthetic && _isVisible && superclass != null) {
+      superclass.addSubclass(this);
     }
 
     if (this.superclass != null) addInherited(superclass);
     interfaces.forEach((interface) => addInherited(interface));
   }
 
   String get packagePrefix => owner.packagePrefix;
 
   String _lookupInClassAndSuperclasses(String name) {
     var lookupFunc = Indexable.determineLookupFunc(name);
@@ skipping 13 matching lines @@
   String findElementInScope(String name) {
     var lookupFunc = Indexable.determineLookupFunc(name);
     var result = _lookupInClassAndSuperclasses(name);
     if (result != null) {
       return result;
     }
     result = owner.findElementInScope(name);
     return result == null ? super.findElementInScope(name) : result;
   }
 
-  markdown.Node fixReferenceWithScope(String name) => fixReference(name);
-
   String get typeName => 'class';
 
-  /// Returns a list of all the parent classes.
-  List<Class> parentChain() {
-    // TODO(efortuna): Seems like we can get rid of this method.
-    var parent = superclass == null ? [] : [superclass];
-    return parent;
-  }
-
   /// Add all inherited variables and methods from the provided superclass.
   /// If [_includePrivate] is true, it also adds the variables and methods from
   /// the superclass.
   void addInherited(Class superclass) {
     inheritedVariables.addAll(superclass.inheritedVariables);
     inheritedVariables.addAll(_allButStatics(superclass.variables));
     addInheritedMethod(superclass, this);
   }
 
   /** [newParent] refers to the actual class is currently using these methods.
@@ skipping 87 matching lines @@
     'qualifiedName': qualifiedName,
     'comment': comment,
     'isAbstract' : isAbstract,
     'superclass': validSuperclass(),
     'implements': interfaces.where((i) => i._isVisible)
         .map((e) => e.qualifiedName).toList(),
     'subclass': (subclasses.toList()..sort())
         .map((x) => x.qualifiedName).toList(),
     'variables': recurseMap(variables),
     'inheritedVariables': recurseMap(inheritedVariables),
-    'methods': expandMethodMap(methods),
-    'inheritedMethods': expandMethodMap(inheritedMethods),
+    '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 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 = Indexable.getDocgenObject(mirror, owningLibrary);
     if (aTypedef is DummyMirror) {
       aTypedef = new Typedef._(mirror, owningLibrary);
     }
     return aTypedef;
   }
 
   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)
   };
 
+  markdown.Node fixReference(String name) => null;
+
   String get typeName => 'typedef';
 
   bool _isValidMirror(DeclarationMirror mirror) => mirror is TypedefMirror;
 }
 
 /// A class containing properties of a Dart variable.
 class Variable extends OwnedIndexable {
 
   bool isFinal;
   bool isStatic;
   bool isConst;
   Type type;
   String _variableName;
 
-  /// List of the meta annotations on the variable.
-  List<Annotation> annotations;
-
   factory Variable(String variableName, VariableMirror mirror,
       Indexable owner) {
     var variable = Indexable.getDocgenObject(mirror);
     if (variable is DummyMirror) {
       return new Variable._(variableName, mirror, owner);
     }
     return variable;
   }
 
   Variable._(this._variableName, VariableMirror mirror, Indexable owner) :
@@ skipping 24 matching lines @@
   String get typeName => 'property';
 
   get comment {
     if (_comment != null) return _comment;
     if (owner is Class) {
       (owner as Class).ensureComments();
     }
     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 = Indexable.getDocgenObject(result);
       if (result is DummyMirror) return packagePrefix + result.docName;
       return result.packagePrefix + result.docName;
     }
 
     if (owner != null) {
@@ skipping 16 matching lines @@
 
   bool isStatic;
   bool isAbstract;
   bool isConst;
   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;
-
-  factory Method(MethodMirror mirror, Indexable owner, // Indexable newOwner.
+  factory Method(MethodMirror mirror, Indexable owner,
       [Method methodInheritedFrom]) {
     var method = Indexable.getDocgenObject(mirror, owner);
     if (method is DummyMirror) {
       method = new Method._(mirror, owner, methodInheritedFrom);
     }
     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 = _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
@@ skipping 63 matching lines @@
     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
+      // This should be NOT from the MIRROR, but from the COMMENT.
+      methodInheritedFrom.comment; // Ensure comment field has been populated.
       _unresolvedComment = methodInheritedFrom._unresolvedComment;
 
-      var linkResolver = (name) => fixReferenceWithScope(name);
+      var linkResolver = (name) => fixReference(name);
       comment = _unresolvedComment == null ? '' :
         markdown.markdownToHtml(_unresolvedComment.trim(),
             linkResolver: linkResolver, inlineSyntaxes: _MARKDOWN_SYNTAXES);
-      commentInheritedFrom = methodInheritedFrom.commentInheritedFrom;
+      commentInheritedFrom = comment != '' ?
+          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.
@@ skipping 112 matching lines @@
         .map((e) => originalMirror.getField(e.simpleName).reflectee)
         .where((e) => e != null)
         .toList();
   }
 
   Map toMap() => {
     'name': Indexable.getDocgenObject(mirror, owningLibrary).docName,
     'parameters': parameters
   };
 }