Rename category to package in remaining places

bin/dartdoc.dart

@@ -190,7 +190,9 @@ main(List<String> arguments) async {
 
   PackageMeta packageMeta = sdkDocs
       ? new PackageMeta.fromSdk(sdkDir,
-          sdkReadmePath: readme, useCategories: args['use-categories'])
+          sdkReadmePath: readme,
+          displayAsPackages:
+              args['use-categories'] || args['display-as-packages'])
       : new PackageMeta.fromDir(inputDir);
 
   if (!packageMeta.isValid) {
@@ -217,7 +219,7 @@ main(List<String> arguments) async {
       footerFilePaths: footerFilePaths,
       footerTextFilePaths: footerTextFilePaths,
       faviconPath: args['favicon'],
-      useCategories: args['use-categories'],
+      displayAsPackages: args['use-categories'],
       prettyIndexJson: args['pretty-index-json']);
 
   for (var generator in generators) {
@@ -257,7 +259,9 @@ main(List<String> arguments) async {
       inputDir: inputDir,
       sdkVersion: sdk.sdkVersion,
       autoIncludeDependencies: args['auto-include-dependencies'],
-      categoryOrder: args['category-order'],
+      packageOrder: args['package-order'].isEmpty
+          ? args['category-order']
+          : args['package-order'],
       reexportMinConfidence:
           double.parse(args['ambiguous-reexport-scorer-min-confidence']),
       verboseWarnings: args['verbose-warnings'],
@@ -342,11 +346,22 @@ ArgParser _createArgsParser() {
   parser.addOption('favicon',
       help: 'A path to a favicon for the generated docs.');
   parser.addFlag('use-categories',
-      help: 'Group libraries from the same package into categories.',
+      help:
+          'Group libraries from the same package in the libraries sidebar. (deprecated, replaced by display-as-packages)',
+      negatable: false,
+      defaultsTo: false);
+  parser.addFlag('display-as-packages',
+      help: 'Group libraries from the same package in the libraries sidebar.',
       negatable: false,
       defaultsTo: false);
   parser.addMultiOption('category-order',
-      help: 'A list of category names to place first when --use-categories is '
+      help:
+          'A list of package names to place first when --display-as-packages is '
+          'set.  Unmentioned categories are sorted after these. (deprecated, replaced by package-order)',
+      splitCommas: true);
+  parser.addMultiOption('package-order',
+      help:
+          'A list of package names to place first when --display-as-packages is '
           'set.  Unmentioned categories are sorted after these.',
       splitCommas: true);
   parser.addFlag('auto-include-dependencies',

lib/dartdoc.dart

@@ -46,14 +46,14 @@ Future<List<Generator>> initGenerators(String url, String relCanonicalPrefix,
     List<String> footerFilePaths,
     List<String> footerTextFilePaths,
     String faviconPath,
-    bool useCategories: false,
+    bool displayAsPackages: false,
     bool prettyIndexJson: false}) async {
   var options = new HtmlGeneratorOptions(
       url: url,
       relCanonicalPrefix: relCanonicalPrefix,
       toolVersion: version,
       faviconPath: faviconPath,
-      useCategories: useCategories,
+      displayAsPackages: displayAsPackages,
       prettyIndexJson: prettyIndexJson);
 
   return [

lib/src/config.dart

@@ -14,7 +14,7 @@ class Config {
   final bool includeSource;
   final String sdkVersion;
   final bool autoIncludeDependencies;
-  final List<String> categoryOrder;
+  final List<String> packageOrder;
   final double reexportMinConfidence;
   final bool verboseWarnings;
   final List<String> dropTextFrom;
@@ -28,7 +28,7 @@ class Config {
       this.includeSource,
       this.sdkVersion,
       this.autoIncludeDependencies,
-      this.categoryOrder,
+      this.packageOrder,
       this.reexportMinConfidence,
       this.verboseWarnings,
       this.dropTextFrom,
@@ -47,7 +47,7 @@ void setConfig(
     bool includeSource: true,
     String sdkVersion,
     bool autoIncludeDependencies: false,
-    List<String> categoryOrder,
+    List<String> packageOrder,
     double reexportMinConfidence: 0.1,
     bool verboseWarnings: true,
     List<String> dropTextFrom,
@@ -61,7 +61,7 @@ void setConfig(
       includeSource,
       sdkVersion,
       autoIncludeDependencies,
-      categoryOrder ?? const <String>[],
+      packageOrder ?? const <String>[],
       reexportMinConfidence,
       verboseWarnings,
       dropTextFrom ?? const <String>[],

lib/src/html/html_generator.dart

@@ -116,7 +116,7 @@ class HtmlGeneratorOptions implements HtmlOptions {
   final bool prettyIndexJson;
 
   @override
-  final bool useCategories;
+  final bool displayAsPackages;
 
   @override
   final String relCanonicalPrefix;
@@ -129,7 +129,7 @@ class HtmlGeneratorOptions implements HtmlOptions {
       this.relCanonicalPrefix,
       this.faviconPath,
       String toolVersion,
-      this.useCategories: false,
+      this.displayAsPackages: false,
       this.prettyIndexJson: false})
       : this.toolVersion = toolVersion ?? 'unknown';
 }

lib/src/html/template_data.dart

@@ -7,7 +7,7 @@ import '../model.dart';
 abstract class HtmlOptions {
   String get relCanonicalPrefix;
   String get toolVersion;
-  bool get useCategories;
+  bool get displayAsPackages;
 }
 
 class Subnav {
@@ -63,7 +63,7 @@ abstract class TemplateData<T extends Documentable> {
   T get self;
   String get version => htmlOptions.toolVersion;
   String get relCanonicalPrefix => htmlOptions.relCanonicalPrefix;
-  bool get useCategories => htmlOptions.useCategories;
+  bool get displayAsPackages => htmlOptions.displayAsPackages;
 
   Iterable<Subnav> getSubNavItems() => <Subnav>[];
 
@@ -113,7 +113,7 @@ class PackageTemplateData extends TemplateData<PackageGraph> {
   String get homepage => packageGraph.homepage;
 
   @override
-  String get kind => (useCategories || packageGraph.isSdk) ? '' : 'package';
+  String get kind => (displayAsPackages || packageGraph.isSdk) ? '' : 'package';
 
   /// `null` for packages because they are at the root – not needed
   @override

lib/src/model.dart

@@ -3991,9 +3991,9 @@ class PackageGraph extends Canonicalization with Nameable, Warnable {
         warningMessage =
             "library says it is {@canonicalFor ${message}} but ${message} can't be canonical there";
         break;
-      case PackageWarning.categoryOrderGivesMissingPackageName:
+      case PackageWarning.packageOrderGivesMissingPackageName:
         warningMessage =
-            "--category-order gives invalid package name: '${message}'";
+            "--package-order gives invalid package name: '${message}'";
         break;
       case PackageWarning.unresolvedDocReference:
         warningMessage = "unresolved doc reference [${message}]";
@@ -4063,17 +4063,18 @@ class PackageGraph extends Canonicalization with Nameable, Warnable {
     return locatable.fullyQualifiedName.replaceFirst(':', '-');
   }
 
-  List<Package> get categories {
-    // Help the user if they pass us a category that doesn't exist.
-    for (String categoryName in config.categoryOrder) {
-      if (!packages.containsKey(categoryName))
-        warnOnElement(null, PackageWarning.categoryOrderGivesMissingPackageName,
-            message: "${categoryName}, categories: ${packages.keys.join(',')}");
+  List<Package> get publicPackages {
+    List<Package> _publicPackages;
+    // Help the user if they pass us a package that doesn't exist.
+    for (String packageName in config.packageOrder) {
+      if (!packages.containsKey(packageName))
+        warnOnElement(null, PackageWarning.packageOrderGivesMissingPackageName,
+            message: "${packageName}, packages: ${packages.keys.join(',')}");
     }
-    List<Package> publicPackages = packages.values
+    _publicPackages = packages.values
         .where((p) => p.libraries.any((l) => l.isPublic))
         .toList();
-    return publicPackages..sort();
+    return _publicPackages..sort();
   }
 
   Map<LibraryElement, Set<Library>> _libraryElementReexportedBy = new Map();
@@ -4200,7 +4201,7 @@ class PackageGraph extends Canonicalization with Nameable, Warnable {
   String get name => packageMeta.name;
 
   String get kind =>
-      (packageMeta.useCategories || packageGraph.isSdk) ? '' : 'package';
+      (packageMeta.displayAsPackages || packageGraph.isSdk) ? '' : 'package';
 
   @override
   String get oneLineDoc => '';
@@ -4492,14 +4493,14 @@ class Package implements Comparable<Package> {
   String toString() => name;
 
   /// Returns:
-  /// -1 if this category is listed in --category-order.
-  /// 0 if this category is the original package we are documenting.
+  /// -1 if this package is listed in --package-order.
+  /// 0 if this package is the original package we are documenting.
   /// 1 if this group represents the Dart SDK.
   /// 2 if this group has a name that contains the name of the original
   ///   package we are documenting.
   /// 3 otherwise.
   int get _group {
-    if (config.categoryOrder.contains(name)) return -1;
+    if (config.packageOrder.contains(name)) return -1;
     if (name.toLowerCase() == packageGraph.name.toLowerCase()) return 0;
     if (name == "Dart Core") return 1;
     if (name.toLowerCase().contains(packageGraph.name.toLowerCase())) return 2;
@@ -4510,8 +4511,8 @@ class Package implements Comparable<Package> {
   int compareTo(Package other) {
     if (_group == other._group) {
       if (_group == -1) {
-        return Comparable.compare(config.categoryOrder.indexOf(name),
-            config.categoryOrder.indexOf(other.name));
+        return Comparable.compare(config.packageOrder.indexOf(name),
+            config.packageOrder.indexOf(other.name));
       } else {
         return name.toLowerCase().compareTo(other.name.toLowerCase());
       }

lib/src/package_meta.dart

@@ -13,15 +13,15 @@ import 'logging.dart';
 
 abstract class PackageMeta {
   final Directory dir;
-  final bool useCategories;
+  final bool displayAsPackages;
 
-  PackageMeta(this.dir, {this.useCategories: false});
+  PackageMeta(this.dir, {this.displayAsPackages: false});
 
   factory PackageMeta.fromDir(Directory dir) => new _FilePackageMeta(dir);
   factory PackageMeta.fromSdk(Directory sdkDir,
-          {String sdkReadmePath, bool useCategories}) =>
+          {String sdkReadmePath, bool displayAsPackages}) =>
       new _SdkMeta(sdkDir,
-          sdkReadmePath: sdkReadmePath, useCategories: useCategories);
+          sdkReadmePath: sdkReadmePath, displayAsPackages: displayAsPackages);
 
   bool get isSdk;
   bool get needsPubGet => false;
@@ -186,8 +186,8 @@ File _locate(Directory dir, List<String> fileNames) {
 class _SdkMeta extends PackageMeta {
   final String sdkReadmePath;
 
-  _SdkMeta(Directory dir, {this.sdkReadmePath, bool useCategories})
-      : super(dir, useCategories: useCategories);
+  _SdkMeta(Directory dir, {this.sdkReadmePath, bool displayAsPackages})
+      : super(dir, displayAsPackages: displayAsPackages);
 
   @override
   bool get isSdk => true;

lib/src/warnings.dart

@@ -52,8 +52,8 @@ final Map<PackageWarning, PackageWarningHelpText> packageWarningText = const {
       PackageWarning.noLibraryLevelDocs,
       "no-library-level-docs",
       "There are no library level docs for this library"),
-  PackageWarning.categoryOrderGivesMissingPackageName: const PackageWarningHelpText(
-      PackageWarning.categoryOrderGivesMissingPackageName,
+  PackageWarning.packageOrderGivesMissingPackageName: const PackageWarningHelpText(
+      PackageWarning.packageOrderGivesMissingPackageName,
       "category-order-gives-missing-package-name",
       "The category-order flag on the command line was given the name of a nonexistent package"),
   PackageWarning.unresolvedDocReference: const PackageWarningHelpText(
@@ -117,7 +117,7 @@ enum PackageWarning {
   ignoredCanonicalFor,
   noCanonicalFound,
   noLibraryLevelDocs,
-  categoryOrderGivesMissingPackageName,
+  packageOrderGivesMissingPackageName,
   unresolvedDocReference,
   unknownMacro,
   brokenLink,

lib/templates/index.html

@@ -3,35 +3,35 @@
   <div class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left">
     <h5>{{self.name}} {{self.kind}}</h5>
 
-    {{#useCategories}}
+    {{#displayAsPackages}}
     <ol>
-      {{#packageGraph.categories}}
+      {{#packageGraph.publicPackages}}
         <li class="section-title">{{name}}</li>
-        {{#libraries}}
+        {{#publicLibraries}}
         <li>{{{linkedName}}}</li>
-        {{/libraries}}
-      {{/packageGraph.categories}}
+        {{/publicLibraries}}
+      {{/packageGraph.publicPackages}}
 
     </ol>
-    {{/useCategories}}
+    {{/displayAsPackages}}
 
-    {{^useCategories}}
+    {{^displayAsPackages}}
     <ol>
       <li class="section-title"><a href="{{packageGraph.href}}#libraries">Libraries</a></li>
       {{#packageGraph.publicLibraries}}
       <li>{{{linkedName}}}</li>
       {{/packageGraph.publicLibraries}}
     </ol>
-    {{/useCategories}}
+    {{/displayAsPackages}}
   </div>
 
   <div class="col-xs-12 col-sm-9 col-md-8 main-content">
     {{#packageGraph}}
       {{>documentation}}
     {{/packageGraph}}
 
-    {{#useCategories}}
-      {{#packageGraph.categories}}
+    {{#displayAsPackages}}
+      {{#packageGraph.publicPackages}}
         <section class="summary">
           <h2>{{name}}</h2>
           <dl>
@@ -45,11 +45,11 @@ <h2>{{name}}</h2>
             {{/libraries}}
           </dl>
         </section>
-      {{/packageGraph.categories}}
+      {{/packageGraph.publicPackages}}
 
-    {{/useCategories}}
+    {{/displayAsPackages}}
 
-    {{^useCategories}}
+    {{^displayAsPackages}}
       <section class="summary" id="libraries">
         <h2>Libraries</h2>
         <dl>
@@ -63,7 +63,7 @@ <h2>Libraries</h2>
           {{/packageGraph.publicLibraries}}
         </dl>
       </section>
-    {{/useCategories}}
+    {{/displayAsPackages}}
 
   </div> <!-- /.main-content -->
 

lib/templates/library.html

@@ -2,25 +2,25 @@
 
   <div class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left">
     <h5>{{parent.name}} {{parent.kind}}</h5>
-    {{#useCategories}}
+    {{#displayAsPackages}}
     <ol>
-      {{#packageGraph.categories}}
+      {{#packageGraph.publicPackages}}
         <li class="section-title">{{name}}</li>
         {{#publicLibraries}}
         <li>{{{linkedName}}}</li>
         {{/publicLibraries}}
-      {{/packageGraph.categories}}
+      {{/packageGraph.publicPackages}}
     </ol>
-    {{/useCategories}}
+    {{/displayAsPackages}}
 
-    {{^useCategories}}
+    {{^displayAsPackages}}
     <ol>
       <li class="section-title"><a href="{{packageGraph.href}}#libraries">Libraries</a></li>
       {{#packageGraph.publicLibraries}}
       <li>{{{linkedName}}}</li>
       {{/packageGraph.publicLibraries}}
     </ol>
-    {{/useCategories}}
+    {{/displayAsPackages}}
   </div>
 
   <div class="col-xs-12 col-sm-9 col-md-8 main-content">