Skip to content

Commit 31833c3

Browse files
srawlinssrawlins
authored
Correctly show extension type ctors and hide enum ctors (#3804)
Fixes #3252 * All enum constructors should be hidden. * All public extension type constructors should be shown.
1 parent 2a39376 commit 31833c3

10 files changed

+127
-91
lines changed

‎lib/src/generator/templates.aot_renderers_for_html.dart

Lines changed: 20 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -548,8 +548,6 @@ String renderEnum(EnumTemplateData context0) {
548548
</dl>
549549
</section>''');
550550
}
551-
buffer.write('\n\n ');
552-
buffer.write(_renderEnum_partial_constructors_9(context2));
553551
buffer.writeln();
554552
if (context2.hasPublicEnumValues) {
555553
buffer.writeln();
@@ -561,32 +559,32 @@ String renderEnum(EnumTemplateData context0) {
561559
var context3 = context2.publicEnumValues;
562560
for (var context4 in context3) {
563561
buffer.write('\n ');
564-
buffer.write(_renderEnum_partial_constant_10(context4));
562+
buffer.write(_renderEnum_partial_constant_9(context4));
565563
}
566564
buffer.writeln();
567565
buffer.write('''
568566
</dl>
569567
</section>''');
570568
}
571569
buffer.write('\n\n ');
572-
buffer.write(_renderEnum_partial_instance_fields_11(context2));
570+
buffer.write(_renderEnum_partial_instance_fields_10(context2));
573571
buffer.write('\n ');
574-
buffer.write(_renderEnum_partial_instance_methods_12(context2));
572+
buffer.write(_renderEnum_partial_instance_methods_11(context2));
575573
buffer.write('\n ');
576-
buffer.write(_renderEnum_partial_instance_operators_13(context2));
574+
buffer.write(_renderEnum_partial_instance_operators_12(context2));
577575
buffer.write('\n ');
578-
buffer.write(_renderEnum_partial_static_properties_14(context2));
576+
buffer.write(_renderEnum_partial_static_properties_13(context2));
579577
buffer.write('\n ');
580-
buffer.write(_renderEnum_partial_static_methods_15(context2));
578+
buffer.write(_renderEnum_partial_static_methods_14(context2));
581579
buffer.write('\n ');
582-
buffer.write(_renderEnum_partial_static_constants_16(context2));
580+
buffer.write(_renderEnum_partial_static_constants_15(context2));
583581
buffer.writeln();
584582
buffer.write('''
585583
</div><!-- /.main-content -->
586584
587585
<div id="dartdoc-sidebar-left" class="sidebar sidebar-offcanvas-left">
588586
''');
589-
buffer.write(_renderEnum_partial_search_sidebar_17(context0));
587+
buffer.write(_renderEnum_partial_search_sidebar_16(context0));
590588
buffer.writeln();
591589
buffer.write('''
592590
<h5>''');
@@ -601,7 +599,7 @@ String renderEnum(EnumTemplateData context0) {
601599
</div><!-- /.sidebar-offcanvas -->
602600
603601
''');
604-
buffer.write(_renderEnum_partial_footer_18(context0));
602+
buffer.write(_renderEnum_partial_footer_17(context0));
605603
buffer.writeln();
606604

607605
return buffer.toString();
@@ -1696,7 +1694,7 @@ String renderSidebarForContainer<T extends Documentable>(
16961694
buffer.write('''<ol>''');
16971695
var context1 = context0.container;
16981696
buffer.writeln();
1699-
if (context1.isClassOrEnum) {
1697+
if (context1.isClassOrExtensionType) {
17001698
if (context1.hasPublicConstructors) {
17011699
buffer.writeln();
17021700
buffer.write('''
@@ -2706,34 +2704,31 @@ String _renderEnum_partial_mixed_in_types_7(Enum context1) {
27062704
String _renderEnum_partial_container_annotations_8(Enum context1) =>
27072705
_deduplicated_lib_templates__container_annotations_html(context1);
27082706

2709-
String _renderEnum_partial_constructors_9(Enum context1) =>
2710-
_deduplicated_lib_templates__constructors_html(context1);
2711-
2712-
String _renderEnum_partial_constant_10(Field context2) =>
2707+
String _renderEnum_partial_constant_9(Field context2) =>
27132708
_deduplicated_lib_templates__constant_html(context2);
27142709

2715-
String _renderEnum_partial_instance_fields_11(Enum context1) =>
2710+
String _renderEnum_partial_instance_fields_10(Enum context1) =>
27162711
_deduplicated_lib_templates__instance_fields_html(context1);
27172712

2718-
String _renderEnum_partial_instance_methods_12(Enum context1) =>
2713+
String _renderEnum_partial_instance_methods_11(Enum context1) =>
27192714
_deduplicated_lib_templates__instance_methods_html(context1);
27202715

2721-
String _renderEnum_partial_instance_operators_13(Enum context1) =>
2716+
String _renderEnum_partial_instance_operators_12(Enum context1) =>
27222717
_deduplicated_lib_templates__instance_operators_html(context1);
27232718

2724-
String _renderEnum_partial_static_properties_14(Enum context1) =>
2719+
String _renderEnum_partial_static_properties_13(Enum context1) =>
27252720
_deduplicated_lib_templates__static_properties_html(context1);
27262721

2727-
String _renderEnum_partial_static_methods_15(Enum context1) =>
2722+
String _renderEnum_partial_static_methods_14(Enum context1) =>
27282723
_deduplicated_lib_templates__static_methods_html(context1);
27292724

2730-
String _renderEnum_partial_static_constants_16(Enum context1) =>
2725+
String _renderEnum_partial_static_constants_15(Enum context1) =>
27312726
_deduplicated_lib_templates__static_constants_html(context1);
27322727

2733-
String _renderEnum_partial_search_sidebar_17(EnumTemplateData context0) =>
2728+
String _renderEnum_partial_search_sidebar_16(EnumTemplateData context0) =>
27342729
_deduplicated_lib_templates__search_sidebar_html(context0);
27352730

2736-
String _renderEnum_partial_footer_18(EnumTemplateData context0) =>
2731+
String _renderEnum_partial_footer_17(EnumTemplateData context0) =>
27372732
_deduplicated_lib_templates__footer_html(context0);
27382733

27392734
String _renderError_partial_head_0(PackageTemplateData context0) =>
@@ -4417,8 +4412,7 @@ String _deduplicated_lib_templates__container_annotations_html(
44174412
return buffer.toString();
44184413
}
44194414

4420-
String _deduplicated_lib_templates__constructors_html(
4421-
InheritingContainer context0) {
4415+
String _deduplicated_lib_templates__constructors_html(Constructable context0) {
44224416
final buffer = StringBuffer();
44234417
if (context0.hasPublicConstructors) {
44244418
buffer.writeln();

‎lib/src/generator/templates.runtime_renderers.dart

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2936,6 +2936,13 @@ class _Renderer_Container extends RendererBase<Container> {
29362936
self.renderSimpleVariable(c, remainingNames, 'bool'),
29372937
getBool: (CT_ c) => c.isClassOrEnum,
29382938
),
2939+
'isClassOrExtensionType': Property(
2940+
getValue: (CT_ c) => c.isClassOrExtensionType,
2941+
renderVariable: (CT_ c, Property<CT_> self,
2942+
List<String> remainingNames) =>
2943+
self.renderSimpleVariable(c, remainingNames, 'bool'),
2944+
getBool: (CT_ c) => c.isClassOrExtensionType,
2945+
),
29392946
'isEnum': Property(
29402947
getValue: (CT_ c) => c.isEnum,
29412948
renderVariable: (CT_ c, Property<CT_> self,
@@ -16294,7 +16301,12 @@ const _invisibleGetters = {
1629416301
'runtimeType',
1629516302
'superclassConstraints'
1629616303
},
16297-
'ModelNode': {'hashCode', 'runtimeType', 'sourceCode'},
16304+
'ModelNode': {
16305+
'commentReferenceData',
16306+
'hashCode',
16307+
'runtimeType',
16308+
'sourceCode'
16309+
},
1629816310
'PackageGraph': {
1629916311
'allConstructedModelElements',
1630016312
'allExtensionsAdded',
@@ -16482,6 +16494,7 @@ const _invisibleGetters = {
1648216494
'aliasedType',
1648316495
'enclosingElement',
1648416496
'hashCode',
16497+
'isAugmentation',
1648516498
'name',
1648616499
'runtimeType'
1648716500
},

‎lib/src/model/constructor.dart

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -31,15 +31,18 @@ class Constructor extends ModelElement with ContainerMember, TypeParameters {
3131
if (!super.isPublic) return false;
3232
if (element.hasPrivateName) return false;
3333
var class_ = element.enclosingElement;
34-
if (class_ is! ClassElement) return true;
35-
if (element.isFactory) return true;
36-
if (class_.isSealed ||
37-
(class_.isAbstract && class_.isFinal) ||
38-
(class_.isAbstract && class_.isInterface)) {
39-
/// Sealed classes, abstract final classes, and abstract interface
40-
/// classes, cannot be instantiated nor extended, from outside the
41-
/// declaring library. Avoid documenting them.
42-
return false;
34+
// Enums cannot be explicitly constructed or extended.
35+
if (class_ is EnumElement) return false;
36+
if (class_ is ClassElement) {
37+
if (element.isFactory) return true;
38+
if (class_.isSealed ||
39+
(class_.isAbstract && class_.isFinal) ||
40+
(class_.isAbstract && class_.isInterface)) {
41+
/// Sealed classes, abstract final classes, and abstract interface
42+
/// classes, cannot be instantiated nor extended, from outside the
43+
/// declaring library. Avoid documenting them.
44+
return false;
45+
}
4346
}
4447
return true;
4548
}

‎lib/src/model/container.dart

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,10 @@ abstract class Container extends ModelElement
5353
/// Whether this is a class or an enum.
5454
bool get isClassOrEnum => element is InterfaceElement;
5555

56+
/// Whether this is a class or an extension type.
57+
bool get isClassOrExtensionType =>
58+
element is ClassElement || element is ExtensionTypeElement;
59+
5660
/// Whether this is a mixin.
5761
bool get isMixin => element is MixinElement;
5862

‎lib/templates/_sidebar_for_container.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
<ol>
22
{{ #container }}
33

4-
{{ #isClassOrEnum }}
4+
{{ #isClassOrExtensionType }}
55
{{ #hasPublicConstructors }}
66
<li class="section-title"><a href="{{{ href }}}#constructors">Constructors</a></li>
77
{{ #publicConstructorsSorted }}
88
<li><a{{ #isDeprecated }} class="deprecated"{{ /isDeprecated }} href="{{{ href }}}">{{ shortName }}</a></li>
99
{{ /publicConstructorsSorted }}
1010
{{ /hasPublicConstructors }}
11-
{{ /isClassOrEnum }}
11+
{{ /isClassOrExtensionType }}
1212

1313
{{ #isEnum }}
1414
{{ #hasPublicEnumValues }}

‎lib/templates/enum.html

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,6 @@ <h1>
2828
</section>
2929
{{ /hasModifiers }}
3030

31-
{{ >constructors }}
32-
3331
{{ #hasPublicEnumValues }}
3432
<section class="summary offset-anchor" id="values">
3533
<h2>Values</h2>

‎test/constructors_test.dart

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,4 +145,78 @@ sealed class C {
145145
expect(c.isPublic, isFalse);
146146
expect(c.documentationAsHtml, '<p>Constructor.</p>');
147147
}
148+
149+
void test_enum_named() async {
150+
var library = await bootPackageWithLibrary('''
151+
enum E {
152+
one.named(), two.named();
153+
/// Constructor.
154+
const E.named();
155+
}
156+
''');
157+
var e = library.enums.named('E').constructors.first;
158+
expect(e.name, equals('E.named'));
159+
expect(e.isPublic, isFalse);
160+
expect(e.documentationAsHtml, '<p>Constructor.</p>');
161+
}
162+
163+
void test_enum_unnamed() async {
164+
var library = await bootPackageWithLibrary('''
165+
enum E {
166+
one(), two();
167+
/// Constructor.
168+
const E();
169+
}
170+
''');
171+
var e = library.enums.named('E').constructors.first;
172+
expect(e.name, equals('E'));
173+
expect(e.isPublic, isFalse);
174+
expect(e.documentationAsHtml, '<p>Constructor.</p>');
175+
}
176+
177+
void test_extensionType_named() async {
178+
var library = await bootPackageWithLibrary('''
179+
extension type ET(int it) {
180+
/// Constructor.
181+
ET.named(this.it);
182+
}
183+
''');
184+
var etNamed =
185+
library.extensionTypes.named('ET').constructors.named('ET.named');
186+
expect(etNamed.name, equals('ET.named'));
187+
expect(etNamed.isPublic, isTrue);
188+
expect(etNamed.documentationAsHtml, '<p>Constructor.</p>');
189+
}
190+
191+
void test_extensionType_primaryNamed() async {
192+
var library = await bootPackageWithLibrary('''
193+
extension type ET.named(int it) {}
194+
''');
195+
var etNamed =
196+
library.extensionTypes.named('ET').constructors.named('ET.named');
197+
expect(etNamed.name, equals('ET.named'));
198+
expect(etNamed.isPublic, isTrue);
199+
}
200+
201+
void test_extensionType_primaryUnnamed() async {
202+
var library = await bootPackageWithLibrary('''
203+
extension type ET(int it) {}
204+
''');
205+
var et = library.extensionTypes.named('ET').constructors.named('ET');
206+
expect(et.name, equals('ET'));
207+
expect(et.isPublic, isTrue);
208+
}
209+
210+
void test_extensionType_unnamed() async {
211+
var library = await bootPackageWithLibrary('''
212+
extension type ET.named(int it) {
213+
/// Constructor.
214+
ET(this.it);
215+
}
216+
''');
217+
var etNamed = library.extensionTypes.named('ET').constructors.named('ET');
218+
expect(etNamed.name, equals('ET'));
219+
expect(etNamed.isPublic, isTrue);
220+
expect(etNamed.documentationAsHtml, '<p>Constructor.</p>');
221+
}
148222
}

‎test/dartdoc_test_base.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ abstract class DartdocTestBase {
3838

3939
String get dartCoreUrlPrefix => 'https://api.dart.dev/stable/3.2.0/dart-core';
4040

41-
String get sdkConstraint => '>=3.2.0 <4.0.0';
41+
String get sdkConstraint => '>=3.3.0 <4.0.0';
4242

4343
List<String> get experiments => [];
4444

‎test/enum_test.dart

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -218,27 +218,6 @@ enum E<T> with M<T>, N { one, two, three; }
218218
expect(eEnum.mixedInElements.map((e) => e.name), equals(['M', 'N']));
219219
}
220220

221-
void test_namedConstructorCanBeReferenced() async {
222-
// TODO(srawlins): As all supported Dart is >=2.15.0, this test can just
223-
// be a "constructors" test rather than an "enum" test.
224-
var library = await bootPackageWithLibrary('''
225-
enum E {
226-
one.named(1),
227-
two.named(2);
228-
229-
const E.named(int x);
230-
}
231-
232-
/// Reference to [E.named].
233-
class C {}
234-
''');
235-
var cClass = library.classes.named('C');
236-
expect(
237-
cClass.documentationAsHtml,
238-
'<p>Reference to <a href="$linkPrefix/E/E.named.html">E.named</a>.</p>',
239-
);
240-
}
241-
242221
void test_operatorsAreDocumented() async {
243222
// TODO(srawlins): As all supported Dart is >=2.15.0, this test can just
244223
// be an "operator" test rather than an "enum" test.

‎test/templates/enum_test.dart

Lines changed: 0 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@ void main() async {
1717
late List<String> eLines;
1818
late List<String> eRightSidebarLines;
1919
late List<String> enumWithDefaultConstructorLines;
20-
late List<String> enumWithDefaultConstructorRightSidebarLines;
2120

2221
group('enums', () {
2322
setUpAll(() async {
@@ -131,11 +130,6 @@ enum EnumWithDefaultConstructor {
131130
packagePath, 'doc', 'lib', 'EnumWithDefaultConstructor.html'))
132131
.readAsStringSync()
133132
.split('\n');
134-
enumWithDefaultConstructorRightSidebarLines = resourceProvider
135-
.getFile(path.join(packagePath, 'doc', 'lib',
136-
'EnumWithDefaultConstructor-enum-sidebar.html'))
137-
.readAsStringSync()
138-
.split('\n');
139133
});
140134

141135
test('enum page contains enum name with generics', () async {
@@ -342,29 +336,6 @@ enum EnumWithDefaultConstructor {
342336
]));
343337
});
344338

345-
test('enum sidebar contains default constructors', () async {
346-
expect(
347-
enumWithDefaultConstructorRightSidebarLines,
348-
containsAllInOrder([
349-
matches('<a href="lib/EnumWithDefaultConstructor.html#constructors">'
350-
'Constructors</a>'),
351-
matches(
352-
'<a href="lib/EnumWithDefaultConstructor/EnumWithDefaultConstructor.html">'
353-
'EnumWithDefaultConstructor</a>'),
354-
]),
355-
);
356-
});
357-
358-
test('enum sidebar contains explicit constructors', () async {
359-
expect(
360-
eRightSidebarLines,
361-
containsAllInOrder([
362-
matches('<a href="lib/E.html#constructors">Constructors</a>'),
363-
matches('<a href="lib/E/E.named.html">named</a>'),
364-
]),
365-
);
366-
});
367-
368339
test('enum sidebar contains values', () async {
369340
expect(
370341
eRightSidebarLines,

0 commit comments

Comments
 (0)