Skip to content

Commit 4214525

Browse files
jcollins-gjcollins-g
authored
Rename category to package in remaining places (#1636)
* Fix or disable miscellaneous lints in dartdoc * Clean up a few more lints. * Rename category to package in all remaining references * dartfmt * Review comments * Fix test failure (accidentally caching config info) * dartfmt * dartfmt * one last rename
1 parent f1808c9 commit 4214525

11 files changed

+84
-68
lines changed

‎bin/dartdoc.dart

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,9 @@ main(List<String> arguments) async {
190190

191191
PackageMeta packageMeta = sdkDocs
192192
? new PackageMeta.fromSdk(sdkDir,
193-
sdkReadmePath: readme, useCategories: args['use-categories'])
193+
sdkReadmePath: readme,
194+
displayAsPackages:
195+
args['use-categories'] || args['display-as-packages'])
194196
: new PackageMeta.fromDir(inputDir);
195197

196198
if (!packageMeta.isValid) {
@@ -217,7 +219,7 @@ main(List<String> arguments) async {
217219
footerFilePaths: footerFilePaths,
218220
footerTextFilePaths: footerTextFilePaths,
219221
faviconPath: args['favicon'],
220-
useCategories: args['use-categories'],
222+
displayAsPackages: args['use-categories'],
221223
prettyIndexJson: args['pretty-index-json']);
222224

223225
for (var generator in generators) {
@@ -257,7 +259,9 @@ main(List<String> arguments) async {
257259
inputDir: inputDir,
258260
sdkVersion: sdk.sdkVersion,
259261
autoIncludeDependencies: args['auto-include-dependencies'],
260-
categoryOrder: args['category-order'],
262+
packageOrder: args['package-order'].isEmpty
263+
? args['category-order']
264+
: args['package-order'],
261265
reexportMinConfidence:
262266
double.parse(args['ambiguous-reexport-scorer-min-confidence']),
263267
verboseWarnings: args['verbose-warnings'],
@@ -342,11 +346,22 @@ ArgParser _createArgsParser() {
342346
parser.addOption('favicon',
343347
help: 'A path to a favicon for the generated docs.');
344348
parser.addFlag('use-categories',
345-
help: 'Group libraries from the same package into categories.',
349+
help:
350+
'Group libraries from the same package in the libraries sidebar. (deprecated, replaced by display-as-packages)',
351+
negatable: false,
352+
defaultsTo: false);
353+
parser.addFlag('display-as-packages',
354+
help: 'Group libraries from the same package in the libraries sidebar.',
346355
negatable: false,
347356
defaultsTo: false);
348357
parser.addMultiOption('category-order',
349-
help: 'A list of category names to place first when --use-categories is '
358+
help:
359+
'A list of package names to place first when --display-as-packages is '
360+
'set. Unmentioned categories are sorted after these. (deprecated, replaced by package-order)',
361+
splitCommas: true);
362+
parser.addMultiOption('package-order',
363+
help:
364+
'A list of package names to place first when --display-as-packages is '
350365
'set. Unmentioned categories are sorted after these.',
351366
splitCommas: true);
352367
parser.addFlag('auto-include-dependencies',

‎lib/dartdoc.dart

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,14 +46,14 @@ Future<List<Generator>> initGenerators(String url, String relCanonicalPrefix,
4646
List<String> footerFilePaths,
4747
List<String> footerTextFilePaths,
4848
String faviconPath,
49-
bool useCategories: false,
49+
bool displayAsPackages: false,
5050
bool prettyIndexJson: false}) async {
5151
var options = new HtmlGeneratorOptions(
5252
url: url,
5353
relCanonicalPrefix: relCanonicalPrefix,
5454
toolVersion: version,
5555
faviconPath: faviconPath,
56-
useCategories: useCategories,
56+
displayAsPackages: displayAsPackages,
5757
prettyIndexJson: prettyIndexJson);
5858

5959
return [

‎lib/src/config.dart

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ class Config {
1414
final bool includeSource;
1515
final String sdkVersion;
1616
final bool autoIncludeDependencies;
17-
final List<String> categoryOrder;
17+
final List<String> packageOrder;
1818
final double reexportMinConfidence;
1919
final bool verboseWarnings;
2020
final List<String> dropTextFrom;
@@ -28,7 +28,7 @@ class Config {
2828
this.includeSource,
2929
this.sdkVersion,
3030
this.autoIncludeDependencies,
31-
this.categoryOrder,
31+
this.packageOrder,
3232
this.reexportMinConfidence,
3333
this.verboseWarnings,
3434
this.dropTextFrom,
@@ -47,7 +47,7 @@ void setConfig(
4747
bool includeSource: true,
4848
String sdkVersion,
4949
bool autoIncludeDependencies: false,
50-
List<String> categoryOrder,
50+
List<String> packageOrder,
5151
double reexportMinConfidence: 0.1,
5252
bool verboseWarnings: true,
5353
List<String> dropTextFrom,
@@ -61,7 +61,7 @@ void setConfig(
6161
includeSource,
6262
sdkVersion,
6363
autoIncludeDependencies,
64-
categoryOrder ?? const <String>[],
64+
packageOrder ?? const <String>[],
6565
reexportMinConfidence,
6666
verboseWarnings,
6767
dropTextFrom ?? const <String>[],

‎lib/src/html/html_generator.dart

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ class HtmlGeneratorOptions implements HtmlOptions {
116116
final bool prettyIndexJson;
117117

118118
@override
119-
final bool useCategories;
119+
final bool displayAsPackages;
120120

121121
@override
122122
final String relCanonicalPrefix;
@@ -129,7 +129,7 @@ class HtmlGeneratorOptions implements HtmlOptions {
129129
this.relCanonicalPrefix,
130130
this.faviconPath,
131131
String toolVersion,
132-
this.useCategories: false,
132+
this.displayAsPackages: false,
133133
this.prettyIndexJson: false})
134134
: this.toolVersion = toolVersion ?? 'unknown';
135135
}

‎lib/src/html/template_data.dart

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import '../model.dart';
77
abstract class HtmlOptions {
88
String get relCanonicalPrefix;
99
String get toolVersion;
10-
bool get useCategories;
10+
bool get displayAsPackages;
1111
}
1212

1313
class Subnav {
@@ -63,7 +63,7 @@ abstract class TemplateData<T extends Documentable> {
6363
T get self;
6464
String get version => htmlOptions.toolVersion;
6565
String get relCanonicalPrefix => htmlOptions.relCanonicalPrefix;
66-
bool get useCategories => htmlOptions.useCategories;
66+
bool get displayAsPackages => htmlOptions.displayAsPackages;
6767

6868
Iterable<Subnav> getSubNavItems() => <Subnav>[];
6969

@@ -113,7 +113,7 @@ class PackageTemplateData extends TemplateData<PackageGraph> {
113113
String get homepage => packageGraph.homepage;
114114

115115
@override
116-
String get kind => (useCategories || packageGraph.isSdk) ? '' : 'package';
116+
String get kind => (displayAsPackages || packageGraph.isSdk) ? '' : 'package';
117117

118118
/// `null` for packages because they are at the root – not needed
119119
@override

‎lib/src/model.dart

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3991,9 +3991,9 @@ class PackageGraph extends Canonicalization with Nameable, Warnable {
39913991
warningMessage =
39923992
"library says it is {@canonicalFor ${message}} but ${message} can't be canonical there";
39933993
break;
3994-
case PackageWarning.categoryOrderGivesMissingPackageName:
3994+
case PackageWarning.packageOrderGivesMissingPackageName:
39953995
warningMessage =
3996-
"--category-order gives invalid package name: '${message}'";
3996+
"--package-order gives invalid package name: '${message}'";
39973997
break;
39983998
case PackageWarning.unresolvedDocReference:
39993999
warningMessage = "unresolved doc reference [${message}]";
@@ -4063,17 +4063,18 @@ class PackageGraph extends Canonicalization with Nameable, Warnable {
40634063
return locatable.fullyQualifiedName.replaceFirst(':', '-');
40644064
}
40654065

4066-
List<Package> get categories {
4067-
// Help the user if they pass us a category that doesn't exist.
4068-
for (String categoryName in config.categoryOrder) {
4069-
if (!packages.containsKey(categoryName))
4070-
warnOnElement(null, PackageWarning.categoryOrderGivesMissingPackageName,
4071-
message: "${categoryName}, categories: ${packages.keys.join(',')}");
4066+
List<Package> get publicPackages {
4067+
List<Package> _publicPackages;
4068+
// Help the user if they pass us a package that doesn't exist.
4069+
for (String packageName in config.packageOrder) {
4070+
if (!packages.containsKey(packageName))
4071+
warnOnElement(null, PackageWarning.packageOrderGivesMissingPackageName,
4072+
message: "${packageName}, packages: ${packages.keys.join(',')}");
40724073
}
4073-
List<Package> publicPackages = packages.values
4074+
_publicPackages = packages.values
40744075
.where((p) => p.libraries.any((l) => l.isPublic))
40754076
.toList();
4076-
return publicPackages..sort();
4077+
return _publicPackages..sort();
40774078
}
40784079

40794080
Map<LibraryElement, Set<Library>> _libraryElementReexportedBy = new Map();
@@ -4200,7 +4201,7 @@ class PackageGraph extends Canonicalization with Nameable, Warnable {
42004201
String get name => packageMeta.name;
42014202

42024203
String get kind =>
4203-
(packageMeta.useCategories || packageGraph.isSdk) ? '' : 'package';
4204+
(packageMeta.displayAsPackages || packageGraph.isSdk) ? '' : 'package';
42044205

42054206
@override
42064207
String get oneLineDoc => '';
@@ -4492,14 +4493,14 @@ class Package implements Comparable<Package> {
44924493
String toString() => name;
44934494

44944495
/// Returns:
4495-
/// -1 if this category is listed in --category-order.
4496-
/// 0 if this category is the original package we are documenting.
4496+
/// -1 if this package is listed in --package-order.
4497+
/// 0 if this package is the original package we are documenting.
44974498
/// 1 if this group represents the Dart SDK.
44984499
/// 2 if this group has a name that contains the name of the original
44994500
/// package we are documenting.
45004501
/// 3 otherwise.
45014502
int get _group {
4502-
if (config.categoryOrder.contains(name)) return -1;
4503+
if (config.packageOrder.contains(name)) return -1;
45034504
if (name.toLowerCase() == packageGraph.name.toLowerCase()) return 0;
45044505
if (name == "Dart Core") return 1;
45054506
if (name.toLowerCase().contains(packageGraph.name.toLowerCase())) return 2;
@@ -4510,8 +4511,8 @@ class Package implements Comparable<Package> {
45104511
int compareTo(Package other) {
45114512
if (_group == other._group) {
45124513
if (_group == -1) {
4513-
return Comparable.compare(config.categoryOrder.indexOf(name),
4514-
config.categoryOrder.indexOf(other.name));
4514+
return Comparable.compare(config.packageOrder.indexOf(name),
4515+
config.packageOrder.indexOf(other.name));
45154516
} else {
45164517
return name.toLowerCase().compareTo(other.name.toLowerCase());
45174518
}

‎lib/src/package_meta.dart

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,15 @@ import 'logging.dart';
1313

1414
abstract class PackageMeta {
1515
final Directory dir;
16-
final bool useCategories;
16+
final bool displayAsPackages;
1717

18-
PackageMeta(this.dir, {this.useCategories: false});
18+
PackageMeta(this.dir, {this.displayAsPackages: false});
1919

2020
factory PackageMeta.fromDir(Directory dir) => new _FilePackageMeta(dir);
2121
factory PackageMeta.fromSdk(Directory sdkDir,
22-
{String sdkReadmePath, bool useCategories}) =>
22+
{String sdkReadmePath, bool displayAsPackages}) =>
2323
new _SdkMeta(sdkDir,
24-
sdkReadmePath: sdkReadmePath, useCategories: useCategories);
24+
sdkReadmePath: sdkReadmePath, displayAsPackages: displayAsPackages);
2525

2626
bool get isSdk;
2727
bool get needsPubGet => false;
@@ -186,8 +186,8 @@ File _locate(Directory dir, List<String> fileNames) {
186186
class _SdkMeta extends PackageMeta {
187187
final String sdkReadmePath;
188188

189-
_SdkMeta(Directory dir, {this.sdkReadmePath, bool useCategories})
190-
: super(dir, useCategories: useCategories);
189+
_SdkMeta(Directory dir, {this.sdkReadmePath, bool displayAsPackages})
190+
: super(dir, displayAsPackages: displayAsPackages);
191191

192192
@override
193193
bool get isSdk => true;

‎lib/src/warnings.dart

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,8 @@ final Map<PackageWarning, PackageWarningHelpText> packageWarningText = const {
5252
PackageWarning.noLibraryLevelDocs,
5353
"no-library-level-docs",
5454
"There are no library level docs for this library"),
55-
PackageWarning.categoryOrderGivesMissingPackageName: const PackageWarningHelpText(
56-
PackageWarning.categoryOrderGivesMissingPackageName,
55+
PackageWarning.packageOrderGivesMissingPackageName: const PackageWarningHelpText(
56+
PackageWarning.packageOrderGivesMissingPackageName,
5757
"category-order-gives-missing-package-name",
5858
"The category-order flag on the command line was given the name of a nonexistent package"),
5959
PackageWarning.unresolvedDocReference: const PackageWarningHelpText(
@@ -117,7 +117,7 @@ enum PackageWarning {
117117
ignoredCanonicalFor,
118118
noCanonicalFound,
119119
noLibraryLevelDocs,
120-
categoryOrderGivesMissingPackageName,
120+
packageOrderGivesMissingPackageName,
121121
unresolvedDocReference,
122122
unknownMacro,
123123
brokenLink,

‎lib/templates/index.html

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,35 +3,35 @@
33
<div class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left">
44
<h5>{{self.name}} {{self.kind}}</h5>
55

6-
{{#useCategories}}
6+
{{#displayAsPackages}}
77
<ol>
8-
{{#packageGraph.categories}}
8+
{{#packageGraph.publicPackages}}
99
<li class="section-title">{{name}}</li>
10-
{{#libraries}}
10+
{{#publicLibraries}}
1111
<li>{{{linkedName}}}</li>
12-
{{/libraries}}
13-
{{/packageGraph.categories}}
12+
{{/publicLibraries}}
13+
{{/packageGraph.publicPackages}}
1414

1515
</ol>
16-
{{/useCategories}}
16+
{{/displayAsPackages}}
1717

18-
{{^useCategories}}
18+
{{^displayAsPackages}}
1919
<ol>
2020
<li class="section-title"><a href="{{packageGraph.href}}#libraries">Libraries</a></li>
2121
{{#packageGraph.publicLibraries}}
2222
<li>{{{linkedName}}}</li>
2323
{{/packageGraph.publicLibraries}}
2424
</ol>
25-
{{/useCategories}}
25+
{{/displayAsPackages}}
2626
</div>
2727

2828
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
2929
{{#packageGraph}}
3030
{{>documentation}}
3131
{{/packageGraph}}
3232

33-
{{#useCategories}}
34-
{{#packageGraph.categories}}
33+
{{#displayAsPackages}}
34+
{{#packageGraph.publicPackages}}
3535
<section class="summary">
3636
<h2>{{name}}</h2>
3737
<dl>
@@ -45,11 +45,11 @@ <h2>{{name}}</h2>
4545
{{/libraries}}
4646
</dl>
4747
</section>
48-
{{/packageGraph.categories}}
48+
{{/packageGraph.publicPackages}}
4949

50-
{{/useCategories}}
50+
{{/displayAsPackages}}
5151

52-
{{^useCategories}}
52+
{{^displayAsPackages}}
5353
<section class="summary" id="libraries">
5454
<h2>Libraries</h2>
5555
<dl>
@@ -63,7 +63,7 @@ <h2>Libraries</h2>
6363
{{/packageGraph.publicLibraries}}
6464
</dl>
6565
</section>
66-
{{/useCategories}}
66+
{{/displayAsPackages}}
6767

6868
</div> <!-- /.main-content -->
6969

‎lib/templates/library.html

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,25 @@
22

33
<div class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left">
44
<h5>{{parent.name}} {{parent.kind}}</h5>
5-
{{#useCategories}}
5+
{{#displayAsPackages}}
66
<ol>
7-
{{#packageGraph.categories}}
7+
{{#packageGraph.publicPackages}}
88
<li class="section-title">{{name}}</li>
99
{{#publicLibraries}}
1010
<li>{{{linkedName}}}</li>
1111
{{/publicLibraries}}
12-
{{/packageGraph.categories}}
12+
{{/packageGraph.publicPackages}}
1313
</ol>
14-
{{/useCategories}}
14+
{{/displayAsPackages}}
1515

16-
{{^useCategories}}
16+
{{^displayAsPackages}}
1717
<ol>
1818
<li class="section-title"><a href="{{packageGraph.href}}#libraries">Libraries</a></li>
1919
{{#packageGraph.publicLibraries}}
2020
<li>{{{linkedName}}}</li>
2121
{{/packageGraph.publicLibraries}}
2222
</ol>
23-
{{/useCategories}}
23+
{{/displayAsPackages}}
2424
</div>
2525

2626
<div class="col-xs-12 col-sm-9 col-md-8 main-content">

0 commit comments

Comments
 (0)