support generic methods (#1282)

* support generic methods

* include in detail page

* update test expectations

* regen test docs

Author: devoncarew

.analysis_options

@@ -1,5 +1,7 @@
 analyzer:
   strong-mode: true
+  language:
+    enableGenericMethods: true
   exclude:
     - 'doc/api/**'
     - 'lib/templates/*.html'

lib/dartdoc.dart

@@ -186,6 +186,7 @@ class DartDoc {
     SourceFactory sourceFactory = new SourceFactory(resolvers);
 
     var options = new AnalysisOptionsImpl();
+    options.enableGenericMethods = true;
 
     AnalysisEngine.instance.processRequiredPlugins();
 

lib/src/html/template_data.dart

@@ -277,7 +277,7 @@ class FunctionTemplateData extends TemplateData<ModelFunction> {
       '${function.name} function - ${library.name} library - Dart API';
   @override
   String get layoutTitle =>
-      _layoutTitle(function.name, 'function', function.isDeprecated);
+      _layoutTitle(function.nameWithGenerics, 'function', function.isDeprecated);
   @override
   String get metaDescription =>
       'API docs for the ${function.name} function from the '
@@ -306,7 +306,7 @@ class MethodTemplateData extends TemplateData<Method> {
       '${library.name} library - Dart API';
   @override
   String get layoutTitle =>
-      _layoutTitle(method.name, method.fullkind, method.isDeprecated);
+      _layoutTitle(method.nameWithGenerics, method.fullkind, method.isDeprecated);
   @override
   String get metaDescription =>
       'API docs for the ${method.name} method from the ${clazz.name} class, '

lib/src/model.dart

@@ -528,6 +528,7 @@ class Class extends ModelElement implements EnclosedElement {
   // problem if we want to show that info later.
   List<ElementType> get mixins => _mixins;
 
+  @override
   String get nameWithGenerics {
     if (!modelType.isParameterizedType) return name;
     return '$name&lt;${_typeParameters.map((t) => t.name).join(', ')}&gt;';
@@ -1221,15 +1222,24 @@ class Method extends ModelElement
     implements EnclosedElement {
   bool _isInherited = false;
   Class _enclosingClass;
+  List<TypeParameter> typeParameters = [];
 
   Method(MethodElement element, Library library) : super(element, library) {
     _modelType = new ElementType(_method.type, this);
+    _calcTypeParameters();
   }
 
   Method.inherited(MethodElement element, this._enclosingClass, Library library)
       : super(element, library) {
     _modelType = new ElementType(_method.type, this);
     _isInherited = true;
+    _calcTypeParameters();
+  }
+
+  void _calcTypeParameters() {
+    typeParameters = _method.typeParameters.map((f) {
+      return new TypeParameter(f, library);
+    }).toList();
   }
 
   @override
@@ -1263,6 +1273,18 @@ class Method extends ModelElement
 
   String get linkedReturnType => modelType.createLinkedReturnTypeName();
 
+  @override
+  String get nameWithGenerics {
+    if (typeParameters.isEmpty) return name;
+    return '$name&lt;${typeParameters.map((t) => t.name).join(', ')}&gt;';
+  }
+
+  @override
+  String get genericParameters {
+    if (typeParameters.isEmpty) return '';
+    return '&lt;${typeParameters.map((t) => t.name).join(', ')}&gt;';
+  }
+
   @override
   Method get overriddenElement {
     ClassElement parent = element.enclosingElement;
@@ -1482,6 +1504,10 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
   @override
   String get name => element.name;
 
+  String get nameWithGenerics => name;
+
+  String get genericParameters => '';
+
   @override
   String get oneLineDoc => _documentation.asOneLiner;
 
@@ -1673,11 +1699,7 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
       }
     }
 
-    var classContent = '';
-    if (isDeprecated) {
-      classContent = 'class="deprecated" ';
-    }
-
+    var classContent = isDeprecated ? 'class="deprecated" ' : '';
     return '<a ${classContent}href="${href}">$name</a>';
   }
 
@@ -1726,9 +1748,18 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
 class ModelFunction extends ModelElement
     with SourceCodeMixin
     implements EnclosedElement {
+  List<TypeParameter> typeParameters = [];
+
   ModelFunction(FunctionElement element, Library library)
       : super(element, library) {
     _modelType = new ElementType(_func.type, this);
+    _calcTypeParameters();
+  }
+
+  void _calcTypeParameters() {
+    typeParameters = _func.typeParameters.map((f) {
+      return new TypeParameter(f, library);
+    }).toList();
   }
 
   @override
@@ -1747,6 +1778,18 @@ class ModelFunction extends ModelElement
 
   String get linkedReturnType => modelType.createLinkedReturnTypeName();
 
+  @override
+  String get nameWithGenerics {
+    if (typeParameters.isEmpty) return name;
+    return '$name&lt;${typeParameters.map((t) => t.name).join(', ')}&gt;';
+  }
+
+  @override
+  String get genericParameters {
+    if (typeParameters.isEmpty) return '';
+    return '&lt;${typeParameters.map((t) => t.name).join(', ')}&gt;';
+  }
+
   FunctionElement get _func => (element as FunctionElement);
 }
 
@@ -2240,6 +2283,7 @@ class Typedef extends ModelElement
       ? modelType.createLinkedReturnTypeName()
       : _typedef.returnType.name;
 
+  @override
   String get nameWithGenerics {
     if (!modelType.isParameterizedType) return name;
     return '$name&lt;${_typeParameters.map((t) => t.name).join(', ')}&gt;';

lib/templates/_callable.html

@@ -1,5 +1,5 @@
 <dt id="{{htmlId}}" class="callable{{ #isInherited }} inherited{{ /isInherited}}">
-  <span class="name{{#isDeprecated}} deprecated{{/isDeprecated}}">{{{linkedName}}}</span><span class="signature">(<wbr>{{{ linkedParamsNoMetadata }}})
+  <span class="name{{#isDeprecated}} deprecated{{/isDeprecated}}">{{{linkedName}}}</span><span class="signature">{{{genericParameters}}}(<wbr>{{{ linkedParamsNoMetadata }}})
     <span class="returntype parameter">&#8594; {{{ linkedReturnType }}}</span>
   </span>
 </dt>

lib/templates/_callable_multiline.html

@@ -8,4 +8,4 @@
 </div>
 {{/hasAnnotations}}
 <span class="returntype">{{{ linkedReturnType }}}</span>
-{{>name_summary}}(<wbr>{{#hasParameters}}{{{linkedParamsLines}}}{{/hasParameters}})
+{{>name_summary}}{{{genericParameters}}}(<wbr>{{#hasParameters}}{{{linkedParamsLines}}}{{/hasParameters}})

test/model_test.dart

@@ -588,7 +588,7 @@ void main() {
     });
 
     test('get methods', () {
-      expect(Dog.instanceMethods, hasLength(5));
+      expect(Dog.instanceMethods, hasLength(6));
     });
 
     test('get operators', () {
@@ -637,7 +637,7 @@ void main() {
     });
 
     test('F has many inherited methods', () {
-      expect(F.inheritedMethods, hasLength(8));
+      expect(F.inheritedMethods, hasLength(9));
       expect(
           F.inheritedMethods.map((im) => im.name),
           equals([
@@ -647,6 +647,7 @@ void main() {
             'noSuchMethod',
             'test',
             'testGeneric',
+            'testGenericMethod',
             'testMethod',
             'toString'
           ]));
@@ -741,6 +742,7 @@ void main() {
       String valueByName(var name) {
         return animal.constants.firstWhere((f) => f.name == name).constantValue;
       }
+
       expect(valueByName('CAT'), equals('const Animal(0)'));
       expect(valueByName('DOG'), equals('const Animal(1)'));
       expect(valueByName('HORSE'), equals('const Animal(2)'));
@@ -759,11 +761,14 @@ void main() {
 
   group('Function', () {
     ModelFunction f1;
+    ModelFunction genericFunction;
     ModelFunction thisIsAsync;
     ModelFunction topLevelFunction;
 
     setUp(() {
-      f1 = exLibrary.functions.single;
+      f1 = exLibrary.functions.first;
+      genericFunction =
+          exLibrary.functions.firstWhere((f) => f.name == 'genericFunction');
       thisIsAsync =
           fakeLibrary.functions.firstWhere((f) => f.name == 'thisIsAsync');
       topLevelFunction =
@@ -848,12 +853,16 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
           '<span class="type-annotation"><a href="fake/Callback2.html">Callback2</a></span> '
           '<span class="parameter-name">callback</span></span>');
     });
+
+    test('supports generic methods', () {
+      expect(genericFunction.nameWithGenerics, 'genericFunction&lt;T&gt;');
+    });
   });
 
   group('Method', () {
     Class classB, klass, HasGenerics, Cat, CatString;
     Method m1, isGreaterThan, m4, m5, m6, m7, convertToMap, abstractMethod;
-    Method inheritedClear, testGeneric;
+    Method inheritedClear, testGeneric, testGenericMethod;
 
     setUp(() {
       klass = exLibrary.classes.singleWhere((c) => c.name == 'Klass');
@@ -879,6 +888,10 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
           .singleWhere((c) => c.name == 'Dog')
           .instanceMethods
           .singleWhere((m) => m.name == 'testGeneric');
+      testGenericMethod = exLibrary.classes
+          .singleWhere((c) => c.name == 'Dog')
+          .instanceMethods
+          .singleWhere((m) => m.name == 'testGenericMethod');
       convertToMap = HasGenerics.instanceMethods
           .singleWhere((m) => m.name == 'convertToMap');
     });
@@ -963,6 +976,10 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
       expect(functionArgParam.modelType.createLinkedReturnTypeName(), 'String');
     });
 
+    test('generic method type args are rendered', () {
+      expect(testGenericMethod.nameWithGenerics, 'testGenericMethod&lt;T&gt;');
+    });
+
     test('doc for method with no return type', () {
       var comment = m5.documentation;
       var comment2 = m6.documentation;

test/src/utils.dart

@@ -79,6 +79,8 @@ class AnalyzerHelper {
     SourceFactory sourceFactory = new SourceFactory(resolvers);
     AnalysisEngine.instance.processRequiredPlugins();
     context = AnalysisEngine.instance.createAnalysisContext();
+    context.analysisOptions = new AnalysisOptionsImpl()
+      ..enableGenericMethods = true;
     context.sourceFactory = sourceFactory;
   }
 

testing/test_package/lib/example.dart

@@ -48,6 +48,10 @@ get y => 2;
 
 int function1(String s, bool b, lastParam) => 5;
 
+T genericFunction<T>(T arg) {
+  return arg;
+}
+
 typedef String processMessage<T>(String msg);
 
 enum Animal {
@@ -227,6 +231,10 @@ class Dog implements Cat, E {
 
   void testMethod(Iterable it) {}
 
+  T testGenericMethod<T>(T arg) {
+    return arg;
+  }
+
   @Deprecated("Internal use")
   static Dog createDog(String s) {
     return new Dog.deprecatedCreate(s);

testing/test_package_docs/ex/Animal-class.html

@@ -97,6 +97,7 @@ <h5><a href="ex/ex-library.html">ex</a></h5>
 
       <li class="section-title"><a href="ex/ex-library.html#functions">Functions</a></li>
       <li><a href="ex/function1.html">function1</a></li>
+      <li><a href="ex/genericFunction.html">genericFunction</a></li>
 
       <li class="section-title"><a href="ex/ex-library.html#enums">Enums</a></li>
       <li><a href="ex/Animal-class.html">Animal</a></li>