Resolve comments lazily and re-evaluate inherited comments for subclasses

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 33 matching lines @@
     '_js_helper.Returns'];
 
 /// Set of libraries declared in the SDK, so libraries that can be accessed
 /// when running dart by default.
 Iterable<LibraryMirror> _sdkLibraries;
 
 /// The dart:core library, which contains all types that are always available
 /// without import.
 LibraryMirror _coreLibrary;
 
-/// Current library being documented to be used for comment links.
-LibraryMirror _currentLibrary;
-
-/// Current class being documented to be used for comment links.
-ClassMirror _currentClass;
-
-/// Current member being documented to be used for comment links.
-MemberMirror _currentMember;
-
 /// Support for [:foo:]-style code comments to the markdown parser.
 List<markdown.InlineSyntax> markdownSyntaxes =
   [new markdown.CodeSyntax(r'\[:\s?((?:.|\n)*?)\s?:\]')];
 
-/// Resolves reference links in doc comments.
-markdown.Resolver linkResolver;
-
 /// Index of all indexable items. This also ensures that no class is
 /// created more than once.
 Map<String, Indexable> entityMap = new Map<String, Indexable>();
 
 /// This is set from the command line arguments flag --include-private
 bool _includePrivate = false;
 
 // 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.
@@ skipping 21 matching lines @@
   if (packageRoot == null && !parseSdk) {
     var type = FileSystemEntity.typeSync(files.first);
     if (type == FileSystemEntityType.DIRECTORY) {
       packageRoot = _findPackageRoot(files.first);
     } 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}');
-  linkResolver = (name) =>
-      fixReference(name, _currentLibrary, _currentClass, _currentMember);
 
   return getMirrorSystem(files, packageRoot: packageRoot, parseSdk: parseSdk)
     .then((MirrorSystem mirrorSystem) {
       if (mirrorSystem.libraries.isEmpty) {
         throw new StateError('No library mirrors were created.');
       }
       var librariesWeAskedFor = _listLibraries(files);
       var librariesWeGot = mirrorSystem.libraries.values.where(
           (each) => each.uri.scheme == 'file');
       _sdkLibraries = mirrorSystem.libraries.values.where(
@@ skipping 13 matching lines @@
       return true;
     });
 }
 
 /// For a library's [mirror], determine the name of the package (if any) we
 /// believe it came from (because of its file URI).
 ///
 /// If [library] is specified, we set the packageName field. If no package could
 /// be determined, we return an empty string.
 String _findPackage(LibraryMirror mirror, [Library library]) {
+  if (mirror == null) return '';
   if (library == null) {
     library = entityMap[mirror.simpleName];
   }
   if (library != null) {
     if (library.hasBeenCheckedForPackage) return library.packageName;
     library.hasBeenCheckedForPackage = true;
   }
   if (mirror.uri.scheme != 'file') return '';
   var filePath = mirror.uri.toFilePath();
   // We assume that we are documenting only libraries under package/lib
@@ skipping 13 matching lines @@
 String _packageIntro(packageDir) {
   var dir = new Directory(packageDir);
   var files = dir.listSync();
   var readmes = files.where((FileSystemEntity each) => (each is File &&
       each.path.substring(packageDir.length + 1, each.path.length)
           .startsWith('README'))).toList();
   if (readmes.isEmpty) return '';
   // If there are multiples, pick the shortest name.
   readmes.sort((a, b) => a.length.compareTo(b.length));
   var readme = readmes.first;
+  var linkResolver = (name) => fixReference(name, null, null, null);
   var contents = markdown.markdownToHtml(readme
     .readAsStringSync(), linkResolver: linkResolver,
     inlineSyntaxes: markdownSyntaxes);
   return contents;
 }
 
 List<String> _listLibraries(List<String> args) {
   var libraries = new List<String>();
   for (var arg in args) {
     var type = FileSystemEntity.typeSync(arg);
@@ skipping 137 matching lines @@
   entityMap.values.where((e) => e is Class).forEach((c) => c.makeValid());
   // Everything is a subclass of Object, therefore empty the list to avoid a
   // giant list of subclasses to be printed out.
   if (includeSdk) (entityMap['dart-core.Object'] as Class).subclasses.clear();
 
   var filteredEntities = entityMap.values.where(_isVisible);
 
   // Outputs a JSON file with all libraries and their preview comments.
   // This will help the viewer know what libraries are available to read in.
   var libraryMap;
+  var linkResolver = (name) => fixReference(name, null, null, null);
   if (append) {
     var docsDir = listDir('docs');
     if (!docsDir.contains('docs/library_list.json')) {
       throw new StateError('No library_list.json');
     }
     libraryMap =
         JSON.decode(new File('docs/library_list.json').readAsStringSync());
     libraryMap['libraries'].addAll(filteredEntities
         .where((e) => e is Library)
         .map((e) => e.previewMap));
@@ skipping 34 matching lines @@
       filteredEntities.map((e) => e.typeName));
   if (append) {
     var previousIndex =
         JSON.decode(new File('docs/index.json').readAsStringSync());
     index.addAll(previousIndex);
   }
   _writeToFile(JSON.encode(index), 'index.json');
 }
 
 Library generateLibrary(dart2js.Dart2JsLibraryMirror library) {
-  _currentLibrary = library;
-  var result = new Library(docName(library), _commentToHtml(library),
+  var result = new Library(docName(library),
+      (actualLibrary) => _commentToHtml(library, actualLibrary),
       _classes(library.classes),
       _methods(library.functions),
       _variables(library.variables),
-      _isHidden(library));
+      _isHidden(library), library);
   _findPackage(library, result);
   logger.fine('Generated library for ${result.name}');
   return result;
 }
 
 void _writeIndexableToFile(Indexable result, bool outputToYaml) {
   var outputFile = result.fileName;
   var output;
   if (outputToYaml) {
     output = getYamlString(result.toMap());
@@ skipping 50 matching lines @@
       .where((e) => e != null)
       .toList();
     if (!skippedAnnotations.contains(docName(annotation.type))) {
       annotations.add(new Annotation(docName(annotation.type),
           parameterList));
     }
   });
   return annotations;
 }
 
-/// Update the global pointers to the current mirror to the particular mirror
-/// we're documenting.
-void _updateCurrentMirror(DeclarationMirror mirror) {
-  if (mirror is LibraryMirror) {
-    _currentLibrary = mirror;
-  } else if (mirror is ClassMirror) {
-    _currentClass = mirror;
-  } else if (mirror is MethodMirror) {
-    _currentMember = mirror;
-  }
-}
-
 /// Returns any documentation comments associated with a mirror with
 /// simple markdown converted to html.
-String _commentToHtml(DeclarationMirror mirror) {
+///
+/// It's possible to have a comment that comes from one mirror applied to
+/// another, in the case of an inherited comment.
+String _commentToHtml(DeclarationMirror mirror, [DeclarationMirror appliedTo]) {
+  if (appliedTo == null) appliedTo = mirror;
   String commentText;
-  _updateCurrentMirror(mirror);
   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}';
         }
       }
     }
   });
 
+  var linkResolver = (name) => fixReferenceWithScope(name, appliedTo);
   commentText = commentText == null ? '' :
       markdown.markdownToHtml(commentText.trim(), linkResolver: linkResolver,
           inlineSyntaxes: markdownSyntaxes);
   return commentText;
 }
 
 /// Generates MDN comments from database.json.
 void _mdnComment(Indexable item) {
   //Check if MDN is loaded.
   if (_mdn == null) {
     // Reading in MDN related json file.
     var root = findRootDirectory();
     var mdnPath = path.join(root, 'utils/apidoc/mdn/database.json');
     _mdn = JSON.decode(new File(mdnPath).readAsStringSync());
   }
-  if (item.comment.isNotEmpty) return;
+  if (item is Library) return;
   var domAnnotation = item.annotations.firstWhere(
       (e) => e.qualifiedName == 'metadata.DomName', orElse: () => null);
   if (domAnnotation == null) return;
   var domName = domAnnotation.parameters.single;
   var parts = domName.split('.');
   if (parts.length == 2) item.comment = _mdnMemberComment(parts[0], parts[1]);
   if (parts.length == 1) item.comment = _mdnTypeComment(parts[0]);
 }
 
 /// Generates the MDN Comment for variables and method DOM elements.
@@ skipping 149 matching lines @@
     ClassMirror currentClass, MemberMirror currentMember) {
   // Attempt the look up the whole name up in the scope.
   String elementName =
       findElementInScope(name, currentLibrary, currentClass, currentMember);
   if (elementName != null) {
     return new markdown.Element.text('a', elementName);
   }
   return _fixComplexReference(name, currentLibrary, currentClass, currentMember);
 }
 
+markdown.Node fixReferenceWithScope(String name, DeclarationMirror scope) {
+  if (scope is LibraryMirror) return fixReference(name, scope, null, null);
+  if (scope is ClassMirror)
+      return fixReference(name, scope.library, scope, null);
+  if (scope is MemberMirror) {
+    var owner = scope.owner;
+    if (owner is ClassMirror) {
+        return fixReference(name, owner.library, owner, scope);
+    } else {
+      return fixReference(name, owner, null, scope);
+    }
+  }
+  return null;
+}
+
 /// Returns a map of [Variable] objects constructed from [mirrorMap].
 Map<String, Variable> _variables(Map<String, VariableMirror> mirrorMap) {
   var data = {};
   // TODO(janicejl): When map to map feature is created, replace the below with
   // a filter. Issue(#9590).
   mirrorMap.forEach((String mirrorName, VariableMirror mirror) {
-    _currentMember = mirror;
     if (_includePrivate || !_isHidden(mirror)) {
       entityMap[docName(mirror)] = new Variable(mirrorName, mirror.isFinal,
          mirror.isStatic, mirror.isConst, _type(mirror.type),
-         _commentToHtml(mirror), _annotations(mirror), docName(mirror),
-         _isHidden(mirror), docName(mirror.owner));
+         (actualVariable) => _commentToHtml(mirror, actualVariable),
+         _annotations(mirror), docName(mirror),
+         _isHidden(mirror), docName(mirror.owner), mirror);
       data[mirrorName] = entityMap[docName(mirror)];
     }
   });
   return data;
 }
 
 /// Returns a map of [Method] objects constructed from [mirrorMap].
 MethodGroup _methods(Map<String, MethodMirror> mirrorMap) {
   var group = new MethodGroup();
   mirrorMap.forEach((String mirrorName, MethodMirror mirror) {
     if (_includePrivate || !mirror.isPrivate) {
       group.addMethod(mirror);
     }
   });
   return group;
 }
 
 /// Returns the [Class] for the given [mirror] has already been created, and if
 /// it does not exist, creates it.
 Class _class(ClassMirror mirror) {
   var clazz = entityMap[docName(mirror)];
   if (clazz == null) {
     var superclass = mirror.superclass != null ?
         _class(mirror.superclass) : null;
     var interfaces =
         mirror.superinterfaces.map((interface) => _class(interface));
-    clazz = new Class(mirror.simpleName, superclass, _commentToHtml(mirror),
+    clazz = new Class(mirror.simpleName, superclass,
+        (actualClass) => _commentToHtml(mirror, actualClass),
         interfaces.toList(), _variables(mirror.variables),
         _methods(mirror.methods), _annotations(mirror), _generics(mirror),
         docName(mirror), _isHidden(mirror), docName(mirror.owner),
-        mirror.isAbstract);
+        mirror.isAbstract, mirror);
     if (superclass != null) clazz.addInherited(superclass);
     interfaces.forEach((interface) => clazz.addInherited(interface));
     entityMap[docName(mirror)] = clazz;
   }
   return clazz;
 }
 
 /// Returns a map of [Class] objects constructed from [mirrorMap].
 ClassGroup _classes(Map<String, ClassMirror> mirrorMap) {
   var group = new ClassGroup();
   mirrorMap.forEach((String mirrorName, ClassMirror mirror) {
       group.addClass(mirror);
   });
   return group;
 }
 
 /// Returns a map of [Parameter] objects constructed from [mirrorList].
 Map<String, Parameter> _parameters(List<ParameterMirror> mirrorList) {
   var data = {};
   mirrorList.forEach((ParameterMirror mirror) {
-    _currentMember = mirror;
     data[mirror.simpleName] = new Parameter(mirror.simpleName,
         mirror.isOptional, mirror.isNamed, mirror.hasDefaultValue,
         _type(mirror.type), mirror.defaultValue,
         _annotations(mirror));
   });
   return data;
 }
 
 /// Returns a map of [Generic] objects constructed from the class mirror.
 Map<String, Generic> _generics(ClassMirror mirror) {
@@ skipping 47 matching lines @@
   inputMap.forEach((key, value) {
     if (value is Map) {
       outputMap[key] = recurseMap(value);
     } else {
       outputMap[key] = value.toMap();
     }
   });
   return outputMap;
 }
 
+/// A type for the function that generates a comment from a mirror.
+typedef String CommentGenerator(Mirror m);
+
 /// A class representing all programming constructs, like library or class.
 class Indexable {
   String name;
   String get qualifiedName => fileName;
   bool isPrivate;
+  Mirror mirror;
 
   // The qualified name (for URL purposes) and the file name are the same,
   // of the form packageName/ClassName or packageName/ClassName.methodName.
   // This defines both the URL and the directory structure.
   String get fileName => packagePrefix + ownerPrefix + name;
 
-  Indexable get owningEntity {
-    var result = entityMap[owner];
-    return result;
-  }
+  Indexable get owningEntity => entityMap[owner];
+
   String get ownerPrefix => owningEntity == null
       ? (owner == null || owner.isEmpty ? '' : owner + '.')
       : owningEntity.qualifiedName + '.';
 
   String get packagePrefix => '';
+
   /// Documentation comment with converted markdown.
-  String comment;
+  String _comment;
+
+  String get comment {
+    if (_comment != null) return _comment;
+    _comment = _commentFunction(mirror);
+    if (_comment.isEmpty) {
+      _mdnComment(this);
+    }
+    return _comment;
+  }
+
+  set comment(x) => _comment = x;
+
+  /// We defer evaluating the comment until we have all the context available
+  CommentGenerator _commentFunction;
 
   /// Qualified Name of the owner of this Indexable Item.
   /// For Library, owner will be "";
   String owner;
 
-  Indexable(this.name, this.comment, this.isPrivate, this.owner);
+  Indexable(this.name, this._commentFunction, this.isPrivate, this.owner,
+      this.mirror);
 
   /// 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>';
@@ skipping 31 matching lines @@
 
   Map get previewMap {
     var basic = super.previewMap;
     basic['packageName'] = packageName;
     if (packageIntro != null) {
       basic['packageIntro'] = packageIntro;
     }
     return basic;
   }
 
-  Library(String name, String comment, this.classes, this.functions,
-      this.variables, bool isPrivate) : super(name, comment,
-          isPrivate, "");
+  Library(String name, Function commentFunction, this.classes, this.functions,
+      this.variables, bool isPrivate, Mirror mirror)
+      : super(name, commentFunction, isPrivate, "", mirror);
 
   /// Generates a map describing the [Library] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'variables': recurseMap(variables),
     'functions': functions.toMap(),
     'classes': classes.toMap(),
     'packageName': packageName,
@@ skipping 26 matching lines @@
 
   /// Generic infomation about the class.
   Map<String, Generic> generics;
 
   Class superclass;
   bool isAbstract;
 
   /// List of the meta annotations on the class.
   List<Annotation> annotations;
 
-  Class(String name, this.superclass, String comment, this.interfaces,
+  /// Make sure that we don't check for inherited comments more than once.
+  bool _commentsEnsured = false;
+
+  Class(String name, this.superclass, Function commentFunction, this.interfaces,
       this.variables, this.methods, this.annotations, this.generics,
-      String qualifiedName, bool isPrivate, String owner, this.isAbstract)
-      : super(name, comment, isPrivate, owner) {
-    _mdnComment(this);
-  }
+      String qualifiedName, bool isPrivate, String owner, this.isAbstract,
+      Mirror mirror)
+      : super(name, commentFunction, isPrivate, owner, mirror);
 
   String get typeName => 'class';
 
   /// Returns a list of all the parent classes.
   List<Class> parent() {
     var parent = superclass == null ? [] : [superclass];
     parent.addAll(interfaces);
     return parent;
   }
 
@@ skipping 45 matching lines @@
       // with the mixin as an owner private too.
       entityMap.values.where((e) => e.owner == qualifiedName)
         .forEach((element) => element.isPrivate = true);
       // Move the subclass up to the next public superclass
       subclasses.forEach((subclass) => addSubclass(subclass));
     }
   }
 
   /// Makes sure that all methods with inherited equivalents have comments.
   void ensureComments() {
+    if (_commentsEnsured) return;
+    _commentsEnsured = true;
     inheritedMethods.forEach((qualifiedName, inheritedMethod) {
       var method = methods[qualifiedName];
       if (method != null) method.ensureCommentFor(inheritedMethod);
     });
   }
 
   /// If a class extends a private superclass, find the closest public superclass
   /// of the private superclass.
   String validSuperclass() {
     if (superclass == null) return 'dart.core.Object';
@@ skipping 23 matching lines @@
   int compareTo(aClass) => name.compareTo(aClass.name);
 }
 
 /// A container to categorize classes into the following groups: abstract
 /// classes, regular classes, typedefs, and errors.
 class ClassGroup {
   Map<String, Class> classes = {};
   Map<String, Typedef> typedefs = {};
   Map<String, Class> errors = {};
 
-  void addClass(ClassMirror mirror) {
-    _currentClass = mirror;
-    if (mirror.isTypedef) {
+  void addClass(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 = _currentClass;
+      var mirror = classMirror;
       if (_includePrivate || !mirror.isPrivate) {
         entityMap[docName(mirror)] = new Typedef(mirror.simpleName,
-            docName(mirror.value.returnType), _commentToHtml(mirror),
+            docName(mirror.value.returnType),
+            (actualTypedef) => _commentToHtml(mirror, actualTypedef),
             _generics(mirror), _parameters(mirror.value.parameters),
             _annotations(mirror), docName(mirror),  _isHidden(mirror),
-            docName(mirror.owner));
+            docName(mirror.owner), mirror);
         typedefs[mirror.simpleName] = entityMap[docName(mirror)];
       }
     } else {
-      var clazz = _class(mirror);
+      var clazz = _class(classMirror);
 
       // Adding inherited parent variables and methods.
       clazz.parent().forEach((parent) {
         if (_isVisible(clazz)) {
           parent.addSubclass(clazz);
         }
       });
 
-      clazz.ensureComments();
-
       if (clazz.isError()) {
-        errors[mirror.simpleName] = clazz;
-      } else if (mirror.isClass) {
-        classes[mirror.simpleName] = clazz;
+        errors[classMirror.simpleName] = clazz;
+      } else if (classMirror.isClass) {
+        classes[classMirror.simpleName] = clazz;
       } else {
-        throw new ArgumentError('${mirror.simpleName} - no class type match. ');
+        throw new ArgumentError(
+            '${classMirror.simpleName} - no class type match. ');
       }
     }
   }
 
   /// 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);
   }
 
   Map toMap() => {
     'class': classes.values.where(_isVisible)
       .map((e) => e.previewMap).toList(),
     'typedef': recurseMap(typedefs),
     'error': errors.values.where(_isVisible)
       .map((e) => e.previewMap).toList()
   };
 }
 
 class Typedef extends Indexable {
   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;
 
-  Typedef(String name, this.returnType, String comment, this.generics,
+  Typedef(String name, this.returnType, Function commentFunction, this.generics,
       this.parameters, this.annotations,
-      String qualifiedName, bool isPrivate, String owner)
-        : super(name, comment, isPrivate, owner);
+      String qualifiedName, bool isPrivate, String owner, Mirror mirror)
+        : super(name, commentFunction, isPrivate, owner, mirror);
 
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'return': returnType,
     'parameters': recurseMap(parameters),
     'annotations': annotations.map((a) => a.toMap()).toList(),
     'generics': recurseMap(generics)
   };
 
   String get typeName => 'typedef';
 }
 
 /// A class containing properties of a Dart variable.
 class Variable extends Indexable {
 
   bool isFinal;
   bool isStatic;
   bool isConst;
   Type type;
 
   /// List of the meta annotations on the variable.
   List<Annotation> annotations;
 
   Variable(String name, this.isFinal, this.isStatic, this.isConst, this.type,
-      String comment, this.annotations, String qualifiedName, bool isPrivate,
-      String owner) : super(name, comment, isPrivate, owner) {
-    _mdnComment(this);
+      Function commentFunction, this.annotations, String qualifiedName,
+      bool isPrivate, String owner, Mirror mirror)
+        : super(name, commentFunction, isPrivate, owner, mirror) {
   }
 
   /// Generates a map describing the [Variable] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'final': isFinal.toString(),
     'static': isStatic.toString(),
     'constant': isConst.toString(),
     '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;
+    var owningClass = owningEntity;
+    if (owningClass is Class) {
+      owningClass.ensureComments();
+    }
+    return super.comment;
+  }
 }
 
 /// A class containing properties of a Dart method.
 class Method extends Indexable {
 
   /// Parameters for this method.
   Map<String, Parameter> parameters;
 
   bool isStatic;
   bool isAbstract;
   bool isConst;
   bool isConstructor;
   bool isGetter;
   bool isSetter;
   bool isOperator;
   Type returnType;
 
   /// Qualified name to state where the comment is inherited from.
   String commentInheritedFrom = "";
 
   /// List of the meta annotations on the method.
   List<Annotation> annotations;
 
   Method(String name, this.isStatic, this.isAbstract, this.isConst,
-      this.returnType, String comment, this.parameters, this.annotations,
+      this.returnType, Function commentFunction, this.parameters,
+      this.annotations,
       String qualifiedName, bool isPrivate, String owner, this.isConstructor,
-      this.isGetter, this.isSetter, this.isOperator)
-        : super(name, comment, isPrivate, owner) {
-    _mdnComment(this);
+      this.isGetter, this.isSetter, this.isOperator, Mirror mirror)
+        : super(name, commentFunction, isPrivate, owner, mirror) {
   }
 
   /// Makes sure that the method with an inherited equivalent have comments.
   void ensureCommentFor(Method inheritedMethod) {
     if (comment.isNotEmpty) return;
-    (entityMap[inheritedMethod.owner] as Class).ensureComments();
-    comment = inheritedMethod.comment;
+    comment = inheritedMethod._commentFunction(mirror);
     commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ?
         inheritedMethod.qualifiedName : inheritedMethod.commentInheritedFrom;
   }
 
   /// Generates a map describing the [Method] object.
   Map toMap() => {
     'name': name,
     'qualifiedName': qualifiedName,
     'comment': comment,
     'commentFrom': commentInheritedFrom,
     'static': isStatic.toString(),
     'abstract': isAbstract.toString(),
     'constant': isConst.toString(),
     'return': new List.filled(1, returnType.toMap()),
     'parameters': recurseMap(parameters),
     'annotations': annotations.map((a) => a.toMap()).toList()
   };
 
   String get typeName => isConstructor ? 'constructor' :
     isGetter ? 'getter' : isSetter ? 'setter' :
     isOperator ? 'operator' : 'method';
+
+  get comment {
+    if (_comment != null) return _comment;
+    var owningClass = owningEntity;
+    if (owningClass is Class) {
+      owningClass.ensureComments();
+    }
+    return super.comment;
+  }
 }
 
 /// A container to categorize methods into the following groups: setters,
 /// getters, constructors, operators, regular methods.
 class MethodGroup {
   Map<String, Method> setters = {};
   Map<String, Method> getters = {};
   Map<String, Method> constructors = {};
   Map<String, Method> operators = {};
   Map<String, Method> regularMethods = {};
 
   void addMethod(MethodMirror mirror) {
     var method = new Method(mirror.simpleName, mirror.isStatic,
         mirror.isAbstract, mirror.isConstConstructor, _type(mirror.returnType),
-        _commentToHtml(mirror), _parameters(mirror.parameters),
+        (actualMethod) => _commentToHtml(mirror, actualMethod),
+        _parameters(mirror.parameters),
         _annotations(mirror), docName(mirror), _isHidden(mirror),
         docName(mirror.owner), mirror.isConstructor, mirror.isGetter,
-        mirror.isSetter, mirror.isOperator);
+        mirror.isSetter, mirror.isOperator, mirror);
     entityMap[docName(mirror)] = method;
-    _currentMember = mirror;
     if (mirror.isSetter) {
       setters[mirror.simpleName] = method;
     } else if (mirror.isGetter) {
       getters[mirror.simpleName] = method;
     } else if (mirror.isConstructor) {
       constructors[mirror.simpleName] = method;
     } else if (mirror.isOperator) {
       operators[mirror.simpleName] = method;
     } else if (mirror.isRegularMethod) {
       regularMethods[mirror.simpleName] = method;
@@ skipping 150 matching lines @@
 /// Remove statics from the map of inherited items before adding them.
 Map _filterStatics(Map items) {
   var result = {};
   items.forEach((name, item) {
     if (!item.isStatic) {
       result[name] = item;
     }
   });
   return result;
 }