Add support for extension methods (#2012)

* Add suport for extensions

* Add options file to test package

* remove path dependencies

* Address review comments

Author: keertip

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.28.6-dev
+* Support for 0.38.2 version of `package:analyzer`.
+* Support generating docs for extension methods (#2001).
+
 ## 0.28.5
 * Support the latest version of `package:analyzer`.
 * Fix hyperlinks to overriden methods (#1994).

analysis_options.yaml

@@ -1,6 +1,9 @@
 include: package:pedantic/analysis_options.1.8.0.yaml
 
 analyzer:
+  # enable for analysis on test package sources.
+  enable-experiment:
+    - extension-methods
   exclude:
     - 'doc/**'
     - 'lib/src/third_party/pkg/**'

dartdoc_options.yaml

@@ -1,4 +1,4 @@
 dartdoc:
   linkToSource:
     root: '.'
-    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v0.28.5/%f%#L%l%'
+    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v0.28.6-dev/%f%#L%l%'

lib/src/element_type.dart

@@ -191,7 +191,7 @@ abstract class DefinedElementType extends ElementType {
   /// would ordinarily do.
   @override
   bool get isPublic {
-    Class canonicalClass =
+    Container canonicalClass =
         element.packageGraph.findCanonicalModelElementFor(element.element) ??
             element;
     return canonicalClass.isPublic;

lib/src/html/html_generator_instance.dart

@@ -171,6 +171,37 @@ class HtmlGeneratorInstance {
           }
         }
 
+        for (var extension in filterNonPublic(lib.extensions)) {
+          generateExtension(_packageGraph, lib, extension);
+
+          for (var constant in filterNonDocumented(extension.constants)) {
+            generateConstant(_packageGraph, lib, extension, constant);
+          }
+
+          for (var property
+              in filterNonDocumented(extension.staticProperties)) {
+            generateProperty(_packageGraph, lib, extension, property);
+          }
+
+          for (var method
+              in filterNonDocumented(extension.allPublicInstanceMethods)) {
+            generateMethod(_packageGraph, lib, extension, method);
+          }
+
+          for (var method in filterNonDocumented(extension.staticMethods)) {
+            generateMethod(_packageGraph, lib, extension, method);
+          }
+
+          for (var operator in filterNonDocumented(extension.allOperators)) {
+            generateMethod(_packageGraph, lib, extension, operator);
+          }
+
+          for (var property
+              in filterNonDocumented(extension.allInstanceFields)) {
+            generateProperty(_packageGraph, lib, extension, property);
+          }
+        }
+
         for (var mixin in filterNonDocumented(lib.mixins)) {
           generateMixins(_packageGraph, lib, mixin);
           for (var constructor in filterNonDocumented(mixin.constructors)) {
@@ -275,6 +306,13 @@ class HtmlGeneratorInstance {
     _build(path.joinAll(clazz.href.split('/')), _templates.classTemplate, data);
   }
 
+  void generateExtension(
+      PackageGraph packageGraph, Library lib, Extension ext) {
+    TemplateData data = ExtensionTemplateData(_options, packageGraph, lib, ext);
+    _build(
+        path.joinAll(ext.href.split('/')), _templates.extensionTemplate, data);
+  }
+
   void generateMixins(PackageGraph packageGraph, Library lib, Mixin mixin) {
     TemplateData data = MixinTemplateData(_options, packageGraph, lib, mixin);
     _build(path.joinAll(mixin.href.split('/')), _templates.mixinTemplate, data);
@@ -305,7 +343,7 @@ class HtmlGeneratorInstance {
   }
 
   void generateMethod(
-      PackageGraph packageGraph, Library lib, Class clazz, Method method) {
+      PackageGraph packageGraph, Library lib, Container clazz, Method method) {
     TemplateData data =
         MethodTemplateData(_options, packageGraph, lib, clazz, method);
 
@@ -314,7 +352,7 @@ class HtmlGeneratorInstance {
   }
 
   void generateConstant(
-      PackageGraph packageGraph, Library lib, Class clazz, Field property) {
+      PackageGraph packageGraph, Library lib, Container clazz, Field property) {
     TemplateData data =
         ConstantTemplateData(_options, packageGraph, lib, clazz, property);
 
@@ -323,7 +361,7 @@ class HtmlGeneratorInstance {
   }
 
   void generateProperty(
-      PackageGraph packageGraph, Library lib, Class clazz, Field property) {
+      PackageGraph packageGraph, Library lib, Container clazz, Field property) {
     TemplateData data =
         PropertyTemplateData(_options, packageGraph, lib, clazz, property);
 

lib/src/html/template_data.dart

@@ -185,6 +185,34 @@ class ClassTemplateData<T extends Class> extends TemplateData<T> {
   }
 }
 
+/// Base template data class for [Extension].
+class ExtensionTemplateData<T extends Extension> extends TemplateData<T> {
+  final T extension;
+  final Library library;
+
+  ExtensionTemplateData(HtmlOptions htmlOptions, PackageGraph packageGraph,
+      this.library, this.extension)
+      : super(htmlOptions, packageGraph);
+
+  @override
+  T get self => extension;
+
+  @override
+  String get title =>
+      '${extension.name} ${extension.kind} - ${library.name} library - Dart API';
+  @override
+  String get metaDescription =>
+      'API docs for the ${extension.name} ${extension.kind} from the '
+      '${library.name} library, for the Dart programming language.';
+
+  @override
+  String get layoutTitle => _layoutTitle(extension.name, extension.kind, false);
+  @override
+  List get navLinks => [packageGraph.defaultPackage, library];
+  @override
+  String get htmlBase => '..';
+}
+
 class ConstructorTemplateData extends TemplateData<Constructor> {
   final Library library;
   final Class clazz;
@@ -255,23 +283,26 @@ class FunctionTemplateData extends TemplateData<ModelFunction> {
 class MethodTemplateData extends TemplateData<Method> {
   final Library library;
   final Method method;
-  final Class clazz;
+  final Container clazz;
+  String container;
 
   MethodTemplateData(HtmlOptions htmlOptions, PackageGraph packageGraph,
       this.library, this.clazz, this.method)
-      : super(htmlOptions, packageGraph);
+      : super(htmlOptions, packageGraph) {
+    container = clazz.isClass ? 'class' : 'extension';
+  }
 
   @override
   Method get self => method;
   @override
-  String get title => '${method.name} method - ${clazz.name} class - '
+  String get title => '${method.name} method - ${clazz.name} ${container} - '
       '${library.name} library - Dart API';
   @override
   String get layoutTitle => _layoutTitle(
       method.nameWithGenerics, method.fullkind, method.isDeprecated);
   @override
   String get metaDescription =>
-      'API docs for the ${method.name} method from the ${clazz.name} class, '
+      'API docs for the ${method.name} method from the ${clazz.name} ${container}, '
       'for the Dart programming language.';
   @override
   List get navLinks => [packageGraph.defaultPackage, library];
@@ -283,25 +314,28 @@ class MethodTemplateData extends TemplateData<Method> {
 
 class PropertyTemplateData extends TemplateData<Field> {
   final Library library;
-  final Class clazz;
+  final Container clazz;
   final Field property;
+  String container;
 
   PropertyTemplateData(HtmlOptions htmlOptions, PackageGraph packageGraph,
       this.library, this.clazz, this.property)
-      : super(htmlOptions, packageGraph);
+      : super(htmlOptions, packageGraph) {
+    container = clazz.isClass ? 'class' : 'extension';
+  }
 
   @override
   Field get self => property;
 
   @override
-  String get title => '${property.name} $type - ${clazz.name} class - '
+  String get title => '${property.name} $type - ${clazz.name} ${container} - '
       '${library.name} library - Dart API';
   @override
   String get layoutTitle =>
       _layoutTitle(property.name, type, property.isDeprecated);
   @override
   String get metaDescription =>
-      'API docs for the ${property.name} $type from the ${clazz.name} class, '
+      'API docs for the ${property.name} $type from the ${clazz.name} ${container}, '
       'for the Dart programming language.';
   @override
   List get navLinks => [packageGraph.defaultPackage, library];
@@ -315,7 +349,7 @@ class PropertyTemplateData extends TemplateData<Field> {
 
 class ConstantTemplateData extends PropertyTemplateData {
   ConstantTemplateData(HtmlOptions htmlOptions, PackageGraph packageGraph,
-      Library library, Class clazz, Field property)
+      Library library, Container clazz, Field property)
       : super(htmlOptions, packageGraph, library, clazz, property);
 
   @override

lib/src/html/templates.dart

@@ -18,6 +18,7 @@ const _partials = <String>[
   'categorization',
   'class',
   'constant',
+  'extension',
   'footer',
   'head',
   'library',
@@ -31,6 +32,7 @@ const _partials = <String>[
   'sidebar_for_class',
   'sidebar_for_category',
   'sidebar_for_enum',
+  'sidebar_for_extension',
   'source_code',
   'source_link',
   'sidebar_for_library',
@@ -45,6 +47,7 @@ const _requiredTemplates = <String>[
   'constant.html',
   'constructor.html',
   'enum.html',
+  'extension.html',
   'function.html',
   'index.html',
   'library.html',
@@ -65,7 +68,6 @@ Future<Map<String, String>> _loadPartials(
     List<String> headerPaths,
     List<String> footerPaths,
     List<String> footerTextPaths) async {
-
   headerPaths ??= [];
   footerPaths ??= [];
   footerTextPaths ??= [];
@@ -75,8 +77,8 @@ Future<Map<String, String>> _loadPartials(
   void replacePlaceholder(String key, String placeholder, List<String> paths) {
     var template = partials[key];
     if (template != null && paths != null && paths.isNotEmpty) {
-      String replacement = paths.map((p) => File(p).readAsStringSync())
-          .join('\n');
+      String replacement =
+          paths.map((p) => File(p).readAsStringSync()).join('\n');
       template = template.replaceAll(placeholder, replacement);
       partials[key] = template;
     }
@@ -140,6 +142,7 @@ class _DirectoryTemplatesLoader extends _TemplatesLoader {
 class Templates {
   final Template categoryTemplate;
   final Template classTemplate;
+  final Template extensionTemplate;
   final Template enumTemplate;
   final Template constantTemplate;
   final Template constructorTemplate;
@@ -164,8 +167,7 @@ class Templates {
         footerTextPaths: footerTextPaths);
   }
 
-  static Future<Templates> fromDirectory(
-      Directory dir,
+  static Future<Templates> fromDirectory(Directory dir,
       {List<String> headerPaths,
       List<String> footerPaths,
       List<String> footerTextPaths}) async {
@@ -185,13 +187,12 @@ class Templates {
     }
   }
 
-  static Future<Templates> _create(
-      _TemplatesLoader templatesLoader,
+  static Future<Templates> _create(_TemplatesLoader templatesLoader,
       {List<String> headerPaths,
       List<String> footerPaths,
       List<String> footerTextPaths}) async {
-    var partials =
-        await _loadPartials(templatesLoader, headerPaths, footerPaths, footerTextPaths);
+    var partials = await _loadPartials(
+        templatesLoader, headerPaths, footerPaths, footerTextPaths);
 
     Template _partial(String name) {
       String partial = partials[name];
@@ -202,14 +203,16 @@ class Templates {
     }
 
     Future<Template> _loadTemplate(String templatePath) async {
-      String templateContents = await templatesLoader.loadTemplate(templatePath);
+      String templateContents =
+          await templatesLoader.loadTemplate(templatePath);
       return Template(templateContents, partialResolver: _partial);
     }
 
     var indexTemplate = await _loadTemplate('index.html');
     var libraryTemplate = await _loadTemplate('library.html');
     var categoryTemplate = await _loadTemplate('category.html');
     var classTemplate = await _loadTemplate('class.html');
+    var extensionTemplate = await _loadTemplate('extension.html');
     var enumTemplate = await _loadTemplate('enum.html');
     var functionTemplate = await _loadTemplate('function.html');
     var methodTemplate = await _loadTemplate('method.html');
@@ -229,6 +232,7 @@ class Templates {
         categoryTemplate,
         libraryTemplate,
         classTemplate,
+        extensionTemplate,
         enumTemplate,
         functionTemplate,
         methodTemplate,
@@ -247,6 +251,7 @@ class Templates {
       this.categoryTemplate,
       this.libraryTemplate,
       this.classTemplate,
+      this.extensionTemplate,
       this.enumTemplate,
       this.functionTemplate,
       this.methodTemplate,

lib/src/markdown_processor.dart

@@ -183,7 +183,7 @@ class IterableBlockParser extends md.BlockParser {
 // Calculate a class hint for findCanonicalModelElementFor.
 ModelElement _getPreferredClass(ModelElement modelElement) {
   if (modelElement is EnclosedElement &&
-      (modelElement as EnclosedElement).enclosingElement is Class) {
+      (modelElement as EnclosedElement).enclosingElement is Container) {
     return (modelElement as EnclosedElement).enclosingElement;
   } else if (modelElement is Class) {
     return modelElement;
@@ -204,7 +204,7 @@ MatchingLinkResult _getMatchingLinkElement(
 
   // Try expensive not-scoped lookup.
   if (refModelElement == null && element is ModelElement) {
-    Class preferredClass = _getPreferredClass(element);
+    Container preferredClass = _getPreferredClass(element);
     refModelElement =
         _MarkdownCommentReference(codeRef, element, commentRefs, preferredClass)
             .computeReferredElement();
@@ -692,7 +692,7 @@ class _MarkdownCommentReference {
   }
 
   // Add a result, but make it canonical.
-  void _addCanonicalResult(ModelElement modelElement, Class tryClass) {
+  void _addCanonicalResult(ModelElement modelElement, Container tryClass) {
     results.add(packageGraph.findCanonicalModelElementFor(modelElement.element,
         preferredClass: tryClass));
   }