Reorder categories and fix enum masthead links (#1373)

* Squash local category-reordering change

* Fix some if statements to have braces (excluding those part of preexisting patterns

* dartfmt

Author: jcollins-g

CHANGELOG.md

@@ -31,6 +31,12 @@
     findCanonicalLibraryFor and findCanonicalModelElementFor.
   * New mixin "Inheritable" helps class members calculate canonicalization
     for inheritable members
+* change order of library, class, and enum members on displayed pages (#1323).
+* change order of categories when using --use-categories, prioritizing
+  this package first, the SDK second, packages with this package's name
+  embedded third, and finally all other packages.  A new flag,
+  --category-order, lets you change what order categories appear in. (#1323)
+* fix broken masthead links in enums (#1225).
 
 ## 0.9.13
 

bin/dartdoc.dart

@@ -11,7 +11,6 @@ import 'package:analyzer/src/dart/sdk/sdk.dart';
 import 'package:analyzer/src/generated/sdk.dart';
 import 'package:args/args.dart';
 import 'package:dartdoc/dartdoc.dart';
-import 'package:dartdoc/src/sdk.dart';
 import 'package:path/path.dart' as path;
 import 'package:stack_trace/stack_trace.dart';
 
@@ -142,14 +141,15 @@ main(List<String> arguments) async {
   DartSdk sdk = new FolderBasedDartSdk(PhysicalResourceProvider.INSTANCE,
       PhysicalResourceProvider.INSTANCE.getFolder(sdkDir.path));
 
-  initializeConfig(
+  setConfig(
       addCrossdart: addCrossdart,
       examplePathPrefix: args['example-path-prefix'],
       showWarnings: args['show-warnings'],
       includeSource: includeSource,
       inputDir: inputDir,
       sdkVersion: sdk.sdkVersion,
-      autoIncludeDependencies: args['auto-include-dependencies']);
+      autoIncludeDependencies: args['auto-include-dependencies'],
+      categoryOrder: args['category-order']);
 
   var dartdoc = new DartDoc(inputDir, excludeLibraries, sdkDir, generators,
       outputDir, packageMeta, includeLibraries,
@@ -194,13 +194,19 @@ ArgParser _createArgsParser() {
   parser.addOption('output',
       help: 'Path to output directory.', defaultsTo: defaultOutDir);
   parser.addOption('header',
-      allowMultiple: true, help: 'path to file containing HTML text.');
+      allowMultiple: true,
+      splitCommas: true,
+      help: 'paths to header files containing HTML text.');
   parser.addOption('footer',
-      allowMultiple: true, help: 'path to file containing HTML text.');
+      allowMultiple: true,
+      splitCommas: true,
+      help: 'paths to footer files containing HTML text.');
   parser.addOption('exclude',
-      allowMultiple: true, help: 'Library names to ignore.');
+      allowMultiple: true, splitCommas: true, help: 'Library names to ignore.');
   parser.addOption('include',
-      allowMultiple: true, help: 'Library names to generate docs for.');
+      allowMultiple: true,
+      splitCommas: true,
+      help: 'Library names to generate docs for.');
   parser.addOption('include-external',
       allowMultiple: true,
       help: 'Additional (external) dart files to include; use "dir/fileName", '
@@ -222,6 +228,11 @@ ArgParser _createArgsParser() {
       help: 'Group libraries from the same package into categories.',
       negatable: false,
       defaultsTo: false);
+  parser.addOption('category-order',
+      help: 'A list of category names to place first when --use-categories is '
+          'set.  Unmentioned categories are sorted after these.',
+      allowMultiple: true,
+      splitCommas: true);
   parser.addFlag('auto-include-dependencies',
       help:
           'Include all the used libraries into the docs, even the ones not in the current package or "include-external"',

lib/dartdoc.dart

@@ -33,10 +33,12 @@ import 'src/model.dart';
 import 'src/model_utils.dart';
 import 'src/package_meta.dart';
 
+export 'src/config.dart';
 export 'src/element_type.dart';
 export 'src/generator.dart';
 export 'src/model.dart';
 export 'src/package_meta.dart';
+export 'src/sdk.dart';
 
 const String name = 'dartdoc';
 // Update when pubspec version changes.
@@ -67,25 +69,6 @@ Future<List<Generator>> initGenerators(String url, List<String> headerFilePaths,
   ];
 }
 
-/// Configure the dartdoc generation process
-void initializeConfig(
-    {Directory inputDir,
-    String sdkVersion,
-    bool showWarnings: false,
-    bool addCrossdart: false,
-    String examplePathPrefix,
-    bool includeSource: true,
-    bool autoIncludeDependencies: false}) {
-  setConfig(
-      inputDir: inputDir,
-      sdkVersion: sdkVersion,
-      showWarnings: showWarnings,
-      addCrossdart: addCrossdart,
-      examplePathPrefix: examplePathPrefix,
-      includeSource: includeSource,
-      autoIncludeDependencies: autoIncludeDependencies);
-}
-
 Map<String, List<fileSystem.Folder>> _calculatePackageMap(
     fileSystem.Folder dir) {
   Map<String, List<fileSystem.Folder>> map = new Map();
@@ -125,7 +108,7 @@ class DartDoc {
   ///
   /// [DartDocResults] is returned if dartdoc succeeds. [DartDocFailure] is
   /// thrown if dartdoc fails in an expected way, for example if there is an
-  /// anaysis error in the code. Any other exception can be throw if there is an
+  /// analysis error in the code. Any other exception can be throw if there is an
   /// unexpected failure.
   Future<DartDocResults> generateDocs() async {
     _stopwatch = new Stopwatch()..start();

lib/src/config.dart

@@ -4,24 +4,27 @@
 
 library dartdoc.config;
 
+import 'dart:collection' show UnmodifiableListView;
 import 'dart:io';
 
 class Config {
   final Directory inputDir;
-  final bool addCrossdart;
   final bool showWarnings;
+  final bool addCrossdart;
   final String examplePathPrefix;
   final bool includeSource;
   final String sdkVersion;
   final bool autoIncludeDependencies;
+  final List<String> categoryOrder;
   Config._(
       this.inputDir,
       this.showWarnings,
       this.addCrossdart,
       this.examplePathPrefix,
       this.includeSource,
       this.sdkVersion,
-      this.autoIncludeDependencies);
+      this.autoIncludeDependencies,
+      this.categoryOrder);
 }
 
 Config _config;
@@ -30,11 +33,22 @@ Config get config => _config;
 void setConfig(
     {Directory inputDir,
     bool showWarnings: false,
-    String sdkVersion,
     bool addCrossdart: false,
     String examplePathPrefix,
     bool includeSource: true,
-    bool autoIncludeDependencies: false}) {
-  _config = new Config._(inputDir, showWarnings, addCrossdart,
-      examplePathPrefix, includeSource, sdkVersion, autoIncludeDependencies);
+    String sdkVersion,
+    bool autoIncludeDependencies: false,
+    List<String> categoryOrder}) {
+  if (categoryOrder == null) {
+    categoryOrder = new UnmodifiableListView<String>([]);
+  }
+  _config = new Config._(
+      inputDir,
+      showWarnings,
+      addCrossdart,
+      examplePathPrefix,
+      includeSource,
+      sdkVersion,
+      autoIncludeDependencies,
+      categoryOrder);
 }

lib/src/html/html_generator_instance.dart

@@ -213,10 +213,10 @@ class HtmlGeneratorInstance implements HtmlOptions {
         _templates.constructorTemplate, data);
   }
 
-  void generateEnum(Package package, Library lib, Class eNum) {
+  void generateEnum(Package package, Library lib, Enum eNum) {
     TemplateData data = new EnumTemplateData(this, package, lib, eNum);
 
-    _build(path.joinAll(eNum.href.split('/')), _templates.classTemplate, data);
+    _build(path.joinAll(eNum.href.split('/')), _templates.enumTemplate, data);
   }
 
   void generateFunction(Package package, Library lib, ModelFunction function) {

lib/src/html/template_data.dart

@@ -119,17 +119,17 @@ class LibraryTemplateData extends TemplateData<Library> {
   List get navLinks => [package];
   @override
   Iterable<Subnav> getSubNavItems() sync* {
+    if (library.hasClasses)
+      yield new Subnav('Classes', '${library.href}#classes');
     if (library.hasConstants)
       yield new Subnav('Constants', '${library.href}#constants');
-    if (library.hasTypedefs)
-      yield new Subnav('Typedefs', '${library.href}#typedefs');
     if (library.hasProperties)
       yield new Subnav('Properties', '${library.href}#properties');
     if (library.hasFunctions)
       yield new Subnav('Functions', '${library.href}#functions');
     if (library.hasEnums) yield new Subnav('Enums', '${library.href}#enums');
-    if (library.hasClasses)
-      yield new Subnav('Classes', '${library.href}#classes');
+    if (library.hasTypedefs)
+      yield new Subnav('Typedefs', '${library.href}#typedefs');
     if (library.hasExceptions)
       yield new Subnav('Exceptions', '${library.href}#exceptions');
   }
@@ -171,20 +171,20 @@ class ClassTemplateData extends TemplateData<Class> {
   String get htmlBase => '..';
   @override
   Iterable<Subnav> getSubNavItems() sync* {
-    if (clazz.hasConstants)
-      yield new Subnav('Constants', '${clazz.href}#constants');
-    if (clazz.hasStaticProperties)
-      yield new Subnav('Static Properties', '${clazz.href}#static-properties');
-    if (clazz.hasStaticMethods)
-      yield new Subnav('Static Methods', '${clazz.href}#static-methods');
-    if (clazz.hasProperties)
-      yield new Subnav('Properties', '${clazz.href}#instance-properties');
     if (clazz.hasConstructors)
       yield new Subnav('Constructors', '${clazz.href}#constructors');
-    if (clazz.hasOperators)
-      yield new Subnav('Operators', '${clazz.href}#operators');
+    if (clazz.hasProperties)
+      yield new Subnav('Properties', '${clazz.href}#instance-properties');
     if (clazz.hasMethods)
       yield new Subnav('Methods', '${clazz.href}#instance-methods');
+    if (clazz.hasOperators)
+      yield new Subnav('Operators', '${clazz.href}#operators');
+    if (clazz.hasStaticProperties)
+      yield new Subnav('Static Properties', '${clazz.href}#static-properties');
+    if (clazz.hasStaticMethods)
+      yield new Subnav('Static Methods', '${clazz.href}#static-methods');
+    if (clazz.hasConstants)
+      yield new Subnav('Constants', '${clazz.href}#constants');
   }
 
   Class get objectType {
@@ -235,30 +235,31 @@ class ConstructorTemplateData extends TemplateData<Constructor> {
 
 class EnumTemplateData extends TemplateData<Enum> {
   EnumTemplateData(
-      HtmlOptions htmlOptions, Package package, this.library, this.clazz)
+      HtmlOptions htmlOptions, Package package, this.library, this.eNum)
       : super(htmlOptions, package);
 
   final Library library;
-  final Enum clazz;
+  final Enum eNum;
   @override
-  Enum get self => clazz;
+  Enum get self => eNum;
   @override
-  String get layoutTitle =>
-      _layoutTitle(clazz.name, 'enum', clazz.isDeprecated);
+  String get layoutTitle => _layoutTitle(eNum.name, 'enum', eNum.isDeprecated);
   @override
   String get title => '${self.name} enum - ${library.name} library - Dart API';
   @override
   String get metaDescription =>
-      'API docs for the ${clazz.name} enum from the ${library.name} library, '
+      'API docs for the ${eNum.name} enum from the ${library.name} library, '
       'for the Dart programming language.';
   @override
   List get navLinks => [package, library];
   @override
   String get htmlBase => '..';
   @override
   Iterable<Subnav> getSubNavItems() => [
-        new Subnav('Constants', '${clazz.href}#constants'),
-        new Subnav('Properties', '${clazz.href}#properties')
+        new Subnav('Constants', '${eNum.href}#constants'),
+        new Subnav('Properties', '${eNum.href}#instance-properties'),
+        new Subnav('Methods', '${eNum.href}#instance-methods'),
+        new Subnav('Operators', '${eNum.href}#operators')
       ];
 }
 

lib/src/html/templates.dart

@@ -26,6 +26,7 @@ const _partials = const <String>[
   'documentation',
   'name_summary',
   'sidebar_for_class',
+  'sidebar_for_enum',
   'source_code',
   'sidebar_for_library',
   'accessor_getter',
@@ -74,6 +75,7 @@ Future<String> _getTemplateFile(String templateFileName) =>
 
 class Templates {
   final TemplateRenderer classTemplate;
+  final TemplateRenderer enumTemplate;
   final TemplateRenderer constantTemplate;
   final TemplateRenderer constructorTemplate;
   final TemplateRenderer functionTemplate;
@@ -105,6 +107,7 @@ class Templates {
     var indexTemplate = await _loadTemplate('index.html');
     var libraryTemplate = await _loadTemplate('library.html');
     var classTemplate = await _loadTemplate('class.html');
+    var enumTemplate = await _loadTemplate('enum.html');
     var functionTemplate = await _loadTemplate('function.html');
     var methodTemplate = await _loadTemplate('method.html');
     var constructorTemplate = await _loadTemplate('constructor.html');
@@ -120,6 +123,7 @@ class Templates {
         indexTemplate,
         libraryTemplate,
         classTemplate,
+        enumTemplate,
         functionTemplate,
         methodTemplate,
         constructorTemplate,
@@ -134,6 +138,7 @@ class Templates {
       this.indexTemplate,
       this.libraryTemplate,
       this.classTemplate,
+      this.enumTemplate,
       this.functionTemplate,
       this.methodTemplate,
       this.constructorTemplate,