Generic function types (#1366)

* Basic support for typedefs with generic functions

* Unit tests for feature

* Better example.

* Add returned type parameter from generic typedef to docs.

* Basic support for typedefs with generic functions

* Unit tests for feature

* Better example.

* Add returned type parameter from generic typedef to docs.

* Prepare 0.9.14-dev for SDK

* Basic support for typedefs with generic functions

* Unit tests for feature

* Better example.

* Add returned type parameter from generic typedef to docs.

* Update changelog and dartfmt

* dartfmt

* update test package docs post merge

* Adjust pubspec.yaml to require the precise version where generic functions were introduced

* rebuild package docs for generic types change + index.json sorting

Author: devoncarew

CHANGELOG.md

@@ -1,4 +1,6 @@
+* Enable support for generic function types.  #1321
 * Update analyzer to 0.30.  #1403
+* Enhancements to css style to better match dartlang.org.  #1372 (partial)
 
 ## 0.11.2
 * Fix regression where warnings generated by the README could result in a fatal exception.  #1409
@@ -111,6 +113,12 @@
   --category-order, lets you change what order categories appear in. (#1323)
 * fix broken masthead links in enums (#1225).
 
+## 0.9.14-dev
+
+This is a prerelease only, features listed as added here don't carry forward.
+
+* Enable support for generic function types (#1321)
+
 ## 0.9.13
 
 * fix grind check-links and check-sdk-links (#1360)

lib/src/model.dart

@@ -2310,9 +2310,11 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
           typeName = mt.linkedName;
         }
         if (typeName.isNotEmpty) {
-          buf.write('<span class="type-annotation">$typeName</span> ');
+          buf.write('<span class="type-annotation">$typeName</span>');
         }
-        if (showNames) {
+        if (typeName.isNotEmpty && showNames && param.name.isNotEmpty)
+          buf.write(' ');
+        if (showNames && param.name.isNotEmpty) {
           buf.write('<span class="parameter-name">${param.name}</span>');
         }
       }
@@ -3775,6 +3777,17 @@ class Typedef extends ModelElement
   String get fileName => '$name.html';
 
   @override
+  String get genericParameters {
+    if (element is GenericTypeAliasElement) {
+      List<TypeParameterElement> genericTypeParameters =
+          (element as GenericTypeAliasElement).function.typeParameters;
+      if (genericTypeParameters.isNotEmpty) {
+        return '&lt;${genericTypeParameters.map((t) => t.name).join(', ')}&gt;';
+      }
+    } // else, all types are resolved.
+    return '';
+  }
+
   String get href {
     if (canonicalLibrary == null) return null;
     return '${canonicalLibrary.dirName}/$fileName';

pubspec.lock

@@ -350,4 +350,4 @@ packages:
     source: hosted
     version: "2.1.12"
 sdks:
-  dart: ">=1.22.0 <2.0.0"
+  dart: ">=1.23.0-dev.11.5 <2.0.0"

pubspec.yaml

@@ -5,7 +5,7 @@ author: Dart Team <[email protected]>
 description: A documentation generator for Dart.
 homepage: https://github.com/dart-lang/dartdoc
 environment:
-  sdk: '>=1.14.0 <2.0.0'
+  sdk: '>=1.23.0-dev.11.5 <2.0.0'
 dependencies:
   analyzer: ^0.30.0
   args: ^0.13.0

test/model_test.dart

@@ -1514,29 +1514,43 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
 
   group('Typedef', () {
     Typedef t;
+    Typedef generic;
 
     setUp(() {
       t = exLibrary.typedefs.firstWhere((t) => t.name == 'processMessage');
+      generic =
+          fakeLibrary.typedefs.firstWhere((t) => t.name == 'NewGenericTypedef');
     });
 
     test('has a fully qualified name', () {
       expect(t.fullyQualifiedName, 'ex.processMessage');
+      expect(generic.fullyQualifiedName, 'fake.NewGenericTypedef');
     });
 
     test('has enclosing element', () {
       expect(t.enclosingElement.name, equals(exLibrary.name));
+      expect(generic.enclosingElement.name, equals(fakeLibrary.name));
     });
 
     test('docs', () {
       expect(t.documentation, equals(''));
+      expect(generic.documentation,
+          equals('A typedef with the new style generic function syntax.'));
     });
 
     test('linked return type', () {
       expect(t.linkedReturnType, equals('String'));
+      expect(generic.linkedReturnType, equals('List<S>'));
     });
 
     test("name with generics", () {
       expect(t.nameWithGenerics, equals('processMessage<T>'));
+      expect(generic.nameWithGenerics, equals('NewGenericTypedef<T>'));
+    });
+
+    test("generic parameters", () {
+      expect(t.genericParameters, equals(''));
+      expect(generic.genericParameters, equals('<S>'));
     });
   });
 

testing/test_package/lib/fake.dart

@@ -134,6 +134,9 @@ typedef String FakeProcesses(String input);
 /// A typedef with a type parameter.
 typedef T GenericTypedef<T>(T input);
 
+/// A typedef with the new style generic function syntax.
+typedef NewGenericTypedef<T> = List<S> Function<S>(T, int, bool);
+
 /// Lots and lots of parameters.
 typedef int LotsAndLotsOfParameters(so, many, parameters, it, should, wrap,
     when, converted, to, html, documentation);
@@ -394,6 +397,11 @@ thisIsAsync() async => 42;
 /// Explicitly returns a Future and is marked async.
 Future thisIsAlsoAsync() async => 43;
 
+/// A generic function with a type parameter.
+void myGenericFunction<S>(int a, bool b, S c) {
+  return;
+}
+
 /// This is a great thing.
 const greatAnnotation = 'great';
 

testing/test_package_docs/css/css-library.html

@@ -76,7 +76,7 @@ <h2>Properties</h2>
       <dl class="properties">
         <dt id="theOnlyThingInTheLibrary" class="property">
           <span class="name"><a href="css/theOnlyThingInTheLibrary.html">theOnlyThingInTheLibrary</a></span><span class="signature">
-            <span class="returntype parameter">&#8596;   <span class="parameter" id="theOnlyThingInTheLibrary=-param-_theOnlyThingInTheLibrary"><span class="type-annotation">String</span> </span> </span>
+            <span class="returntype parameter">&#8596;   <span class="parameter" id="theOnlyThingInTheLibrary=-param-_theOnlyThingInTheLibrary"><span class="type-annotation">String</span></span> </span>
           </span>
         </dt>
         <dd>

testing/test_package_docs/ex/Apple-class.html

@@ -163,7 +163,7 @@ <h2>Properties</h2>
 </dd>
         <dt id="m" class="property">
           <span class="name"><a href="ex/Apple/m.html">m</a></span><span class="signature">
-            <span class="returntype parameter">&#8596;   <span class="parameter" id="m=-param-_m"><span class="type-annotation">int</span> </span> </span>
+            <span class="returntype parameter">&#8596;   <span class="parameter" id="m=-param-_m"><span class="type-annotation">int</span></span> </span>
           </span>
         </dt>
         <dd>
@@ -306,7 +306,7 @@ <h2>Static Properties</h2>
       <dl class="properties">
         <dt id="string" class="property">
           <span class="name"><a href="ex/Apple/string.html">string</a></span><span class="signature">
-            <span class="returntype parameter">&#8596;   <span class="parameter" id="string=-param-_string"><span class="type-annotation">String</span> </span> </span>
+            <span class="returntype parameter">&#8596;   <span class="parameter" id="string=-param-_string"><span class="type-annotation">String</span></span> </span>
           </span>
         </dt>
         <dd>

testing/test_package_docs/ex/B-class.html

@@ -154,7 +154,7 @@ <h2>Properties</h2>
       <dl class="properties">
         <dt id="autoCompress" class="property">
           <span class="name"><a href="ex/B/autoCompress.html">autoCompress</a></span><span class="signature">
-            <span class="returntype parameter">&#8596;   <span class="parameter" id="autoCompress=-param-_autoCompress"><span class="type-annotation">bool</span> </span> </span>
+            <span class="returntype parameter">&#8596;   <span class="parameter" id="autoCompress=-param-_autoCompress"><span class="type-annotation">bool</span></span> </span>
           </span>
         </dt>
         <dd>
@@ -172,7 +172,7 @@ <h2>Properties</h2>
 </dd>
         <dt id="list" class="property">
           <span class="name"><a href="ex/B/list.html">list</a></span><span class="signature">
-            <span class="returntype parameter">&#8596;   <span class="parameter" id="list=-param-_list"><span class="type-annotation">List&lt;String&gt;</span> </span> </span>
+            <span class="returntype parameter">&#8596;   <span class="parameter" id="list=-param-_list"><span class="type-annotation">List&lt;String&gt;</span></span> </span>
           </span>
         </dt>
         <dd>
@@ -205,7 +205,7 @@ <h2>Properties</h2>
 </dd>
         <dt id="m" class="property inherited">
           <span class="name"><a href="ex/Apple/m.html">m</a></span><span class="signature">
-            <span class="returntype parameter">&#8596;   <span class="parameter" id="m=-param-_m"><span class="type-annotation">int</span> </span> </span>
+            <span class="returntype parameter">&#8596;   <span class="parameter" id="m=-param-_m"><span class="type-annotation">int</span></span> </span>
           </span>
         </dt>
         <dd class="inherited">

testing/test_package_docs/ex/Dog-class.html

@@ -191,7 +191,7 @@ <h2>Properties</h2>
 </dd>
         <dt id="deprecatedField" class="property">
           <span class="name deprecated"><a class="deprecated" href="ex/Dog/deprecatedField.html">deprecatedField</a></span><span class="signature">
-            <span class="returntype parameter">&#8596;   <span class="parameter" id="deprecatedField=-param-_deprecatedField"><span class="type-annotation">int</span> </span> </span>
+            <span class="returntype parameter">&#8596;   <span class="parameter" id="deprecatedField=-param-_deprecatedField"><span class="type-annotation">int</span></span> </span>
           </span>
         </dt>
         <dd>
@@ -225,7 +225,7 @@ <h2>Properties</h2>
 </dd>
         <dt id="name" class="property">
           <span class="name"><a href="ex/Dog/name.html">name</a></span><span class="signature">
-            <span class="returntype parameter">&#8596;   <span class="parameter" id="name=-param-_name"><span class="type-annotation">String</span> </span> </span>
+            <span class="returntype parameter">&#8596;   <span class="parameter" id="name=-param-_name"><span class="type-annotation">String</span></span> </span>
           </span>
         </dt>
         <dd>