Skip to content

Commit 10e2cfc

Browse files
srawlinssrawlins
authored
Improve display text for libraries (#3552)
1 parent ab845cb commit 10e2cfc

13 files changed

+338
-133
lines changed

‎lib/src/element_type.dart‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,12 @@ abstract class ElementType
6464
/// Name with generics and nullability indication.
6565
String get nameWithGenerics;
6666

67+
@override
68+
String get displayName => throw UnimplementedError();
69+
70+
@override
71+
String get breadcrumbName => throw UnimplementedError();
72+
6773
DartType get instantiatedType;
6874

6975
Iterable<ElementType> get typeArguments;

‎lib/src/generator/generator_frontend.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ class GeneratorFrontEnd implements Generator {
7474

7575
for (var lib in filterNonDocumented(package.libraries)) {
7676
if (!multiplePackages) {
77-
logInfo('Generating docs for library ${lib.name} from '
77+
logInfo('Generating docs for library ${lib.breadcrumbName} from '
7878
'${lib.element.source.uri}...');
7979
}
8080
if (!lib.isAnonymous && !lib.hasDocumentation) {

‎lib/src/generator/template_data.dart‎

Lines changed: 77 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,11 @@ abstract class TemplateData<T extends Documentable> extends TemplateDataBase {
103103

104104
String? get belowSidebarPath => self.belowSidebarPath;
105105

106-
String _layoutTitle(String name, String kind, {required bool isDeprecated}) =>
106+
String _layoutTitle(
107+
String name, {
108+
String? kind,
109+
bool isDeprecated = false,
110+
}) =>
107111
_packageGraph.rendererFactory.templateRenderer
108112
.composeLayoutTitle(name, kind, isDeprecated);
109113
}
@@ -136,8 +140,11 @@ class PackageTemplateData extends TemplateData<Package> {
136140
Package get self => package;
137141

138142
@override
139-
String get layoutTitle =>
140-
_layoutTitle(package.name, package.kind.toString(), isDeprecated: false);
143+
String get layoutTitle => _layoutTitle(
144+
package.name,
145+
kind: package.kind.toString(),
146+
);
147+
141148
@override
142149
String get metaDescription =>
143150
'${package.name} API docs, for the Dart programming language.';
@@ -183,9 +190,10 @@ class CategoryTemplateData extends TemplateData<Category>
183190
String get title => '${category.name} ${category.kind} - Dart API';
184191

185192
@override
186-
String get layoutTitle =>
187-
_layoutTitle(category.name, category.kind.toString(),
188-
isDeprecated: false);
193+
String get layoutTitle => _layoutTitle(
194+
category.name,
195+
kind: category.kind.toString(),
196+
);
189197

190198
@override
191199
String get metaDescription =>
@@ -215,8 +223,10 @@ class LibraryTemplateData extends TemplateData<Library>
215223
List<Documentable> get navLinks => [_packageGraph.defaultPackage];
216224

217225
@override
218-
String get layoutTitle => _layoutTitle(library.name, Kind.library.toString(),
219-
isDeprecated: library.isDeprecated);
226+
String get layoutTitle => _layoutTitle(
227+
library.breadcrumbName,
228+
isDeprecated: library.isDeprecated,
229+
);
220230

221231
@override
222232
Library get self => library;
@@ -284,9 +294,12 @@ abstract class InheritingContainerTemplateData<T extends InheritingContainer>
284294
'${library.name} library, for the Dart programming language.';
285295

286296
@override
287-
String get layoutTitle =>
288-
_layoutTitle(clazz.nameWithLinkedGenerics, clazz.fullkind,
289-
isDeprecated: clazz.isDeprecated);
297+
String get layoutTitle => _layoutTitle(
298+
clazz.nameWithLinkedGenerics,
299+
kind: clazz.fullkind,
300+
isDeprecated: clazz.isDeprecated,
301+
);
302+
290303
@override
291304
List<Documentable> get navLinks => [_packageGraph.defaultPackage, library];
292305
}
@@ -321,9 +334,12 @@ class ExtensionTemplateData<T extends Extension> extends TemplateData<T>
321334
'${library.name} library, for the Dart programming language.';
322335

323336
@override
324-
String get layoutTitle =>
325-
_layoutTitle(extension.name, extension.kind.toString(),
326-
isDeprecated: false);
337+
String get layoutTitle => _layoutTitle(
338+
extension.name, kind: extension.kind.toString(),
339+
// TODO(srawlins): Why can't an extension be deprecated?
340+
isDeprecated: false,
341+
);
342+
327343
@override
328344
List<Documentable> get navLinks => [_packageGraph.defaultPackage, library];
329345
}
@@ -359,9 +375,12 @@ final class ExtensionTypeTemplateData<T extends ExtensionType>
359375
'${library.name} library, for the Dart programming language.';
360376

361377
@override
362-
String get layoutTitle =>
363-
_layoutTitle(extensionType.name, extensionType.kind.toString(),
364-
isDeprecated: false);
378+
String get layoutTitle => _layoutTitle(
379+
extensionType.name,
380+
kind: extensionType.kind.toString(),
381+
// TODO(srawlins): Use real deprecation here.
382+
isDeprecated: false,
383+
);
365384

366385
@override
367386
List<Documentable> get navLinks => [_packageGraph.defaultPackage, library];
@@ -391,8 +410,12 @@ class ConstructorTemplateData extends TemplateData<Constructor>
391410
Constructor get self => constructor;
392411

393412
@override
394-
String get layoutTitle => _layoutTitle(constructor.name, constructor.fullKind,
395-
isDeprecated: constructor.isDeprecated);
413+
String get layoutTitle => _layoutTitle(
414+
constructor.name,
415+
kind: constructor.fullKind,
416+
isDeprecated: constructor.isDeprecated,
417+
);
418+
396419
@override
397420
List<Documentable> get navLinks => [_packageGraph.defaultPackage, library];
398421
@override
@@ -440,10 +463,14 @@ class FunctionTemplateData extends TemplateData<ModelFunction>
440463
@override
441464
String get title =>
442465
'${function.name} function - ${library.name} library - Dart API';
466+
443467
@override
444-
String get layoutTitle =>
445-
_layoutTitle(function.nameWithGenerics, Kind.function.toString(),
446-
isDeprecated: function.isDeprecated);
468+
String get layoutTitle => _layoutTitle(
469+
function.nameWithGenerics,
470+
kind: Kind.function.toString(),
471+
isDeprecated: function.isDeprecated,
472+
);
473+
447474
@override
448475
String get metaDescription =>
449476
'API docs for the ${function.name} function from the '
@@ -478,10 +505,14 @@ class MethodTemplateData extends TemplateData<Method>
478505
String get title =>
479506
'${method.name} method - ${container.name} ${container.kind} - '
480507
'${library.name} library - Dart API';
508+
481509
@override
482-
String get layoutTitle =>
483-
_layoutTitle(method.nameWithGenerics, method.fullkind,
484-
isDeprecated: method.isDeprecated);
510+
String get layoutTitle => _layoutTitle(
511+
method.nameWithGenerics,
512+
kind: method.fullkind,
513+
isDeprecated: method.isDeprecated,
514+
);
515+
485516
@override
486517
String get metaDescription =>
487518
'API docs for the ${method.name} method from the ${container.name} '
@@ -518,9 +549,14 @@ class PropertyTemplateData extends TemplateData<Field>
518549
String get title => '${property.name} ${property.kind} - '
519550
'${container.name} ${container.kind} - '
520551
'${library.name} library - Dart API';
552+
521553
@override
522-
String get layoutTitle => _layoutTitle(property.name, property.fullkind,
523-
isDeprecated: property.isDeprecated);
554+
String get layoutTitle => _layoutTitle(
555+
property.name,
556+
kind: property.fullkind,
557+
isDeprecated: property.isDeprecated,
558+
);
559+
524560
@override
525561
String get metaDescription =>
526562
'API docs for the ${property.name} ${property.kind} from the '
@@ -552,10 +588,14 @@ class TypedefTemplateData extends TemplateData<Typedef>
552588
@override
553589
String get title =>
554590
'${typeDef.name} typedef - ${library.name} library - Dart API';
591+
555592
@override
556-
String get layoutTitle =>
557-
_layoutTitle(typeDef.nameWithGenerics, Kind.typedef.toString(),
558-
isDeprecated: typeDef.isDeprecated);
593+
String get layoutTitle => _layoutTitle(
594+
typeDef.nameWithGenerics,
595+
kind: Kind.typedef.toString(),
596+
isDeprecated: typeDef.isDeprecated,
597+
);
598+
559599
@override
560600
String get metaDescription =>
561601
'API docs for the ${typeDef.name} typedef from the '
@@ -584,9 +624,14 @@ class TopLevelPropertyTemplateData extends TemplateData<TopLevelVariable>
584624
@override
585625
String get title =>
586626
'${property.name} $_type - ${library.name} library - Dart API';
627+
587628
@override
588-
String get layoutTitle =>
589-
_layoutTitle(property.name, _type, isDeprecated: property.isDeprecated);
629+
String get layoutTitle => _layoutTitle(
630+
property.name,
631+
kind: _type,
632+
isDeprecated: property.isDeprecated,
633+
);
634+
590635
@override
591636
String get metaDescription =>
592637
'API docs for the ${property.name} $_type from the '

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

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1109,17 +1109,25 @@ String renderLibrary(LibraryTemplateData context0) {
11091109
var context1 = context0.self;
11101110
buffer.writeln();
11111111
buffer.write('''
1112-
<div>''');
1112+
<div>
1113+
''');
11131114
buffer.write(_renderLibrary_partial_source_link_1(context1));
1114-
buffer.write('''<h1><span class="kind-library">''');
1115-
buffer.write(context1.name);
1116-
buffer.write('''</span> ''');
1115+
buffer.writeln();
1116+
buffer.write('''
1117+
<h1>
1118+
<span class="kind-library">''');
1119+
buffer.write(context1.displayName);
1120+
buffer.write('''</span>
1121+
''');
11171122
buffer.writeEscaped(context1.kind.toString());
11181123
buffer.write(' ');
11191124
buffer.write(_renderLibrary_partial_feature_set_2(context1));
11201125
buffer.write(' ');
11211126
buffer.write(_renderLibrary_partial_categorization_3(context1));
1122-
buffer.write('''</h1></div>''');
1127+
buffer.writeln();
1128+
buffer.write('''
1129+
</h1>
1130+
</div>''');
11231131
buffer.writeln();
11241132
var context2 = context0.library;
11251133
buffer.write('\n ');
@@ -3579,7 +3587,7 @@ String _deduplicated_lib_templates_html__head_html(TemplateDataBase context0) {
35793587
<li><a href="''');
35803588
buffer.write(context4.href);
35813589
buffer.write('''">''');
3582-
buffer.writeEscaped(context4.name);
3590+
buffer.writeEscaped(context4.breadcrumbName);
35833591
buffer.write('''</a></li>''');
35843592
}
35853593
var context5 = context0.navLinksWithGenerics;
@@ -3589,7 +3597,7 @@ String _deduplicated_lib_templates_html__head_html(TemplateDataBase context0) {
35893597
<li><a href="''');
35903598
buffer.write(context6.href);
35913599
buffer.write('''">''');
3592-
buffer.writeEscaped(context6.name);
3600+
buffer.writeEscaped(context6.breadcrumbName);
35933601
if (context6.hasGenericParameters == true) {
35943602
buffer.write('''<span class="signature">''');
35953603
buffer.write(context6.genericParameters);

0 commit comments

Comments
 (0)