Skip to content

Commit f04164b

Browse files
jcollins-gjcollins-g
authored
Introduce basic generic type alias support for dartdoc (#2558)
* initial implementation * getting somewhere. mostly works now and no regressions. * refactor to extract function typedefs * cleanup and tests pass * more tweaks * merge leftover * add markdown and more test cases * dartfmt
1 parent cab6931 commit f04164b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+271
-88
lines changed

‎lib/src/element_type.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -273,7 +273,7 @@ abstract class DefinedElementType extends ElementType {
273273

274274
@override
275275
List<Parameter> get parameters =>
276-
element.canHaveParameters ? element.parameters : [];
276+
element.isCallable ? element.parameters : [];
277277

278278
ModelElement get returnElement => element;
279279
ElementType _returnType;

‎lib/src/generator/templates.dart

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,10 @@ const _partials_html = <String>[
4242
'source_code',
4343
'source_link',
4444
'sidebar_for_library',
45+
'type',
46+
'type_multiline',
47+
'typedef',
48+
'typedef_multiline',
4549
'accessor_getter',
4650
'accessor_setter',
4751
];
@@ -66,6 +70,10 @@ const _partials_md = <String>[
6670
'property',
6771
'source_code',
6872
'source_link',
73+
'type',
74+
'type_multiline',
75+
'typedef',
76+
'typedef_multiline',
6977
];
7078

7179
abstract class _TemplatesLoader {

‎lib/src/model/getter_setter_combo.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ mixin GetterSetterCombo on ModelElement {
190190
}
191191

192192
@override
193-
bool get canHaveParameters => hasSetter;
193+
bool get isCallable => hasSetter;
194194

195195
@override
196196
List<Parameter> get parameters => setter.parameters;

‎lib/src/model/library.dart

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -104,9 +104,9 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
104104
compilationUnit.enums,
105105
compilationUnit.extensions,
106106
compilationUnit.functions,
107-
compilationUnit.functionTypeAliases,
108107
compilationUnit.mixins,
109108
compilationUnit.topLevelVariables,
109+
compilationUnit.typeAliases,
110110
compilationUnit.types,
111111
]);
112112
}
@@ -493,7 +493,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
493493
@override
494494
List<Typedef> get typedefs {
495495
_typedefs ??= _exportedAndLocalElements
496-
.whereType<FunctionTypeAliasElement>()
496+
.whereType<TypeAliasElement>()
497497
.map((e) => ModelElement.from(e, this, packageGraph) as Typedef)
498498
.toList(growable: false);
499499
return _typedefs;

‎lib/src/model/model_element.dart

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ library dartdoc.models;
88
import 'dart:convert';
99

1010
import 'package:analyzer/dart/element/element.dart';
11+
import 'package:analyzer/dart/element/type.dart' show FunctionType;
1112
import 'package:analyzer/source/line_info.dart';
1213
import 'package:analyzer/src/dart/element/element.dart';
1314
import 'package:analyzer/src/dart/element/member.dart'
@@ -333,7 +334,10 @@ abstract class ModelElement extends Canonicalization
333334
assert(e.enclosingElement.name != '');
334335
return ModelFunctionTypedef(e, library, packageGraph);
335336
}
336-
if (e is FunctionTypeAliasElement) {
337+
if (e is TypeAliasElement) {
338+
if (e.aliasedType is FunctionType) {
339+
return FunctionTypedef(e, library, packageGraph);
340+
}
337341
return Typedef(e, library, packageGraph);
338342
}
339343
if (e is ConstructorElement) {
@@ -543,10 +547,8 @@ abstract class ModelElement extends Canonicalization
543547
return allFeatures.join(', ');
544548
}
545549

546-
bool get canHaveParameters =>
547-
element is ExecutableElement ||
548-
element is FunctionTypedElement ||
549-
element is FunctionTypeAliasElement;
550+
bool get isCallable =>
551+
element is FunctionTypedElement || element is FunctionTypeAliasElement;
550552

551553
ModelElement buildCanonicalModelElement() {
552554
Container preferredClass;
@@ -998,9 +1000,9 @@ abstract class ModelElement extends Canonicalization
9981000
}
9991001
} else if (element is ClassElement) {
10001002
_modelType = ElementType.from(element.thisType, library, packageGraph);
1001-
} else if (element is FunctionTypeAliasElement) {
1003+
} else if (element is TypeAliasElement) {
10021004
_modelType =
1003-
ElementType.from(element.function.type, library, packageGraph);
1005+
ElementType.from(element.aliasedType, library, packageGraph);
10041006
} else if (element is FunctionTypedElement) {
10051007
_modelType = ElementType.from(element.type, library, packageGraph);
10061008
} else if (element is ParameterElement) {
@@ -1050,7 +1052,7 @@ abstract class ModelElement extends Canonicalization
10501052
(this as GetterSetterCombo).setter != null) {
10511053
newParameters.addAll((this as GetterSetterCombo).setter.parameters);
10521054
} else {
1053-
if (canHaveParameters) newParameters.addAll(parameters);
1055+
if (isCallable) newParameters.addAll(parameters);
10541056
}
10551057
while (newParameters.isNotEmpty) {
10561058
recursedParameters.addAll(newParameters);
@@ -1070,7 +1072,7 @@ abstract class ModelElement extends Canonicalization
10701072
path.Context get pathContext => packageGraph.resourceProvider.pathContext;
10711073

10721074
List<Parameter> get parameters {
1073-
if (!canHaveParameters) {
1075+
if (!isCallable) {
10741076
throw StateError('$element cannot have parameters');
10751077
}
10761078

‎lib/src/model/typedef.dart

Lines changed: 32 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,21 @@
33
// BSD-style license that can be found in the LICENSE file.
44

55
import 'package:analyzer/dart/element/element.dart';
6-
import 'package:dartdoc/src/element_type.dart';
6+
import 'package:analyzer/dart/element/type.dart';
77
import 'package:dartdoc/src/model/model.dart';
88
import 'package:dartdoc/src/render/typedef_renderer.dart';
99

1010
class Typedef extends ModelElement
1111
with TypeParameters, Categorization
1212
implements EnclosedElement {
13-
Typedef(FunctionTypeAliasElement element, Library library,
14-
PackageGraph packageGraph)
13+
Typedef(TypeAliasElement element, Library library, PackageGraph packageGraph)
1514
: super(element, library, packageGraph);
1615

16+
DartType get aliasedType => element.aliasedType;
17+
18+
@override
19+
TypeAliasElement get element => super.element;
20+
1721
@override
1822
ModelElement get enclosingElement => library;
1923

@@ -23,12 +27,8 @@ class Typedef extends ModelElement
2327
@override
2428
String get genericParameters => _renderer.renderGenericParameters(this);
2529

26-
List<TypeParameterElement> get genericTypeParameters {
27-
if (element is FunctionTypeAliasElement) {
28-
return (element as FunctionTypeAliasElement).function.typeParameters;
29-
}
30-
return Iterable<TypeParameterElement>.empty();
31-
}
30+
List<TypeParameterElement> get genericTypeParameters =>
31+
element.typeParameters;
3232

3333
@override
3434
String get filePath => '${library.dirName}/$fileName';
@@ -52,17 +52,31 @@ class Typedef extends ModelElement
5252
String get linkedReturnType => modelType.createLinkedReturnTypeName();
5353

5454
@override
55-
// TODO(jcollins-g): change to FunctionTypeElementType after analyzer 0.41
56-
// ignore: unnecessary_overrides
57-
ElementType get modelType => super.modelType;
58-
59-
FunctionTypeAliasElement get _typedef =>
60-
(element as FunctionTypeAliasElement);
61-
62-
@override
63-
List<TypeParameter> get typeParameters => _typedef.typeParameters.map((f) {
55+
List<TypeParameter> get typeParameters => element.typeParameters.map((f) {
6456
return ModelElement.from(f, library, packageGraph) as TypeParameter;
6557
}).toList();
6658

6759
TypedefRenderer get _renderer => packageGraph.rendererFactory.typedefRenderer;
6860
}
61+
62+
/// A typedef referring to a function type.
63+
class FunctionTypedef extends Typedef {
64+
FunctionTypedef(
65+
TypeAliasElement element, Library library, PackageGraph packageGraph)
66+
: super(element, library, packageGraph);
67+
68+
@override
69+
FunctionType get aliasedType => super.aliasedType;
70+
71+
@override
72+
List<TypeParameterElement> get genericTypeParameters {
73+
var aliasedTypeElement = aliasedType.element;
74+
if (aliasedTypeElement is FunctionTypedElement) {
75+
return aliasedTypeElement.typeParameters;
76+
}
77+
if (aliasedType.typeFormals.isNotEmpty == true) {
78+
return aliasedType.typeFormals;
79+
}
80+
return super.genericTypeParameters;
81+
}
82+
}

‎lib/templates/html/_callable_multiline.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,6 @@
77
</ol>
88
</div>
99
{{/hasAnnotations}}
10+
1011
<span class="returntype">{{{ linkedReturnType }}}</span>
1112
{{>name_summary}}{{{genericParameters}}}(<wbr>{{#hasParameters}}{{{linkedParamsLines}}}{{/hasParameters}})

‎lib/templates/html/_name_summary.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{{#isConst}}const {{/isConst}}<span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{name}}</span>
1+
{{#isConst}}const {{/isConst}}<span class="name {{#isDeprecated}}deprecated{{/isDeprecated}}">{{name}}</span>

‎lib/templates/html/_type.html

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<dt id="{{htmlId}}" class="{{ #isInherited }} inherited{{ /isInherited}}">
2+
<span class="name{{#isDeprecated}} deprecated{{/isDeprecated}}">{{{linkedName}}}</span>{{{linkedGenericParameters}}}
3+
=
4+
<span class="returntype parameter">{{{ linkedReturnType }}}</span>
5+
</span>
6+
{{>categorization}}
7+
</dt>
8+
<dd{{ #isInherited }} class="inherited"{{ /isInherited}}>
9+
{{{ oneLineDoc }}} {{{ extendedDocLink }}}
10+
{{>features}}
11+
</dd>

‎lib/templates/html/_type_multiline.html

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{{#hasAnnotations}}
2+
<div>
3+
<ol class="annotation-list">
4+
{{#annotations}}
5+
<li>{{{.}}}</li>
6+
{{/annotations}}
7+
</ol>
8+
</div>
9+
{{/hasAnnotations}}
10+
{{>name_summary}}{{{genericParameters}}} = <span class="returntype"> {{{linkedReturnType}}}</span>

‎lib/templates/html/_typedef.html

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{{#isCallable}}
2+
{{>callable}}
3+
{{/isCallable}}
4+
{{^isCallable}}
5+
{{>type}}
6+
{{/isCallable}}

‎lib/templates/html/_typedef_multiline.html

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{{#isCallable}}
2+
{{>callable_multiline}}
3+
{{/isCallable}}
4+
{{^isCallable}}
5+
{{>type_multiline}}
6+
{{/isCallable}}

‎lib/templates/html/category.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ <h2>Typedefs</h2>
101101

102102
<dl class="callables">
103103
{{#publicTypedefsSorted}}
104-
{{>callable}}
104+
{{>typedef}}
105105
{{/publicTypedefsSorted}}
106106
</dl>
107107
</section>
@@ -126,4 +126,4 @@ <h5>{{self.name}} {{self.kind}}</h5>
126126
{{>sidebar_for_category}}
127127
</div>
128128
<!--/sidebar-offcanvas-right-->
129-
{{>footer}}
129+
{{>footer}}

‎lib/templates/html/library.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,9 @@ <h2>Enums</h2>
103103
<section class="summary offset-anchor" id="typedefs">
104104
<h2>Typedefs</h2>
105105

106-
<dl class="callables">
106+
<dl>
107107
{{#library.publicTypedefsSorted}}
108-
{{>callable}}
108+
{{>typedef}}
109109
{{/library.publicTypedefsSorted}}
110110
</dl>
111111
</section>

‎lib/templates/html/typedef.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ <h5>{{parent.name}} {{parent.kind}}</h5>
1313

1414
<section class="multi-line-signature">
1515
{{#typeDef}}
16-
{{>callable_multiline}}
16+
{{>typedef_multiline}}
1717
{{/typeDef}}
1818
</section>
1919

‎lib/templates/md/_type.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
##### {{{linkedName}}}{{{linkedGenericParameters}}}({{{ linkedParamsNoMetadata }}}) {{{ linkedReturnType }}}
2+
{{>categorization}}
3+
4+
{{{ oneLineDoc }}} {{{ extendedDocLink }}} {{!two spaces intentional}}
5+
{{>features}}

‎lib/templates/md/_type_multiline.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{{#hasAnnotations}}
2+
{{#annotations}}
3+
- {{{.}}}
4+
{{/annotations}}
5+
{{/hasAnnotations}}
6+
7+
{{>name_summary}}{{{genericParameters}}} = {{{linkedReturnType}}}

‎lib/templates/md/_typedef.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{{#isCallable}}
2+
{{>callable}}
3+
{{/isCallable}}
4+
{{^isCallable}}
5+
{{>type}}
6+
{{/isCallable}}

‎lib/templates/md/_typedef_multiline.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{{#isCallable}}
2+
{{>callable_multiline}}
3+
{{/isCallable}}
4+
{{^isCallable}}
5+
{{>type_multiline}}
6+
{{/isCallable}}

‎lib/templates/md/category.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@
7272
## Typedefs
7373

7474
{{#publicTypedefsSorted}}
75-
{{>callable}}
75+
{{>typedef}}
7676

7777
{{/publicTypedefsSorted}}
7878
{{/hasPublicTypedefs}}

‎lib/templates/md/library.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@
7979
## Typedefs
8080

8181
{{#library.publicTypedefsSorted}}
82-
{{>callable}}
82+
{{>typedef}}
8383

8484
{{/library.publicTypedefsSorted}}
8585
{{/library.hasPublicTypedefs}}

‎lib/templates/md/typedef.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
{{/self}}
1010

1111
{{#typeDef}}
12-
{{>callable_multiline}}
12+
{{>typedef_multiline}}
1313

1414
{{>documentation}}
1515

‎pubspec.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ environment:
77
sdk: '>=2.11.99 <3.0.0'
88

99
dependencies:
10-
analyzer: ^1.0.0
10+
analyzer: ^1.1.0
1111
args: ^2.0.0
1212
charcode: ^1.2.0
1313
collection: ^1.2.0

0 commit comments

Comments
 (0)