Skip to content

Commit 5c9f166

Browse files
authored
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
1 parent 47b60b4 commit 5c9f166

File tree

568 files changed

+8782
-8384
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

568 files changed

+8782
-8384
lines changed

CHANGELOG.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@
3131
findCanonicalLibraryFor and findCanonicalModelElementFor.
3232
* New mixin "Inheritable" helps class members calculate canonicalization
3333
for inheritable members
34+
* change order of library, class, and enum members on displayed pages (#1323).
35+
* change order of categories when using --use-categories, prioritizing
36+
this package first, the SDK second, packages with this package's name
37+
embedded third, and finally all other packages. A new flag,
38+
--category-order, lets you change what order categories appear in. (#1323)
39+
* fix broken masthead links in enums (#1225).
3440

3541
## 0.9.13
3642

bin/dartdoc.dart

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@ import 'package:analyzer/src/dart/sdk/sdk.dart';
1111
import 'package:analyzer/src/generated/sdk.dart';
1212
import 'package:args/args.dart';
1313
import 'package:dartdoc/dartdoc.dart';
14-
import 'package:dartdoc/src/sdk.dart';
1514
import 'package:path/path.dart' as path;
1615
import 'package:stack_trace/stack_trace.dart';
1716

@@ -142,14 +141,15 @@ main(List<String> arguments) async {
142141
DartSdk sdk = new FolderBasedDartSdk(PhysicalResourceProvider.INSTANCE,
143142
PhysicalResourceProvider.INSTANCE.getFolder(sdkDir.path));
144143

145-
initializeConfig(
144+
setConfig(
146145
addCrossdart: addCrossdart,
147146
examplePathPrefix: args['example-path-prefix'],
148147
showWarnings: args['show-warnings'],
149148
includeSource: includeSource,
150149
inputDir: inputDir,
151150
sdkVersion: sdk.sdkVersion,
152-
autoIncludeDependencies: args['auto-include-dependencies']);
151+
autoIncludeDependencies: args['auto-include-dependencies'],
152+
categoryOrder: args['category-order']);
153153

154154
var dartdoc = new DartDoc(inputDir, excludeLibraries, sdkDir, generators,
155155
outputDir, packageMeta, includeLibraries,
@@ -194,13 +194,19 @@ ArgParser _createArgsParser() {
194194
parser.addOption('output',
195195
help: 'Path to output directory.', defaultsTo: defaultOutDir);
196196
parser.addOption('header',
197-
allowMultiple: true, help: 'path to file containing HTML text.');
197+
allowMultiple: true,
198+
splitCommas: true,
199+
help: 'paths to header files containing HTML text.');
198200
parser.addOption('footer',
199-
allowMultiple: true, help: 'path to file containing HTML text.');
201+
allowMultiple: true,
202+
splitCommas: true,
203+
help: 'paths to footer files containing HTML text.');
200204
parser.addOption('exclude',
201-
allowMultiple: true, help: 'Library names to ignore.');
205+
allowMultiple: true, splitCommas: true, help: 'Library names to ignore.');
202206
parser.addOption('include',
203-
allowMultiple: true, help: 'Library names to generate docs for.');
207+
allowMultiple: true,
208+
splitCommas: true,
209+
help: 'Library names to generate docs for.');
204210
parser.addOption('include-external',
205211
allowMultiple: true,
206212
help: 'Additional (external) dart files to include; use "dir/fileName", '
@@ -222,6 +228,11 @@ ArgParser _createArgsParser() {
222228
help: 'Group libraries from the same package into categories.',
223229
negatable: false,
224230
defaultsTo: false);
231+
parser.addOption('category-order',
232+
help: 'A list of category names to place first when --use-categories is '
233+
'set. Unmentioned categories are sorted after these.',
234+
allowMultiple: true,
235+
splitCommas: true);
225236
parser.addFlag('auto-include-dependencies',
226237
help:
227238
'Include all the used libraries into the docs, even the ones not in the current package or "include-external"',

lib/dartdoc.dart

Lines changed: 3 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,12 @@ import 'src/model.dart';
3333
import 'src/model_utils.dart';
3434
import 'src/package_meta.dart';
3535

36+
export 'src/config.dart';
3637
export 'src/element_type.dart';
3738
export 'src/generator.dart';
3839
export 'src/model.dart';
3940
export 'src/package_meta.dart';
41+
export 'src/sdk.dart';
4042

4143
const String name = 'dartdoc';
4244
// Update when pubspec version changes.
@@ -67,25 +69,6 @@ Future<List<Generator>> initGenerators(String url, List<String> headerFilePaths,
6769
];
6870
}
6971

70-
/// Configure the dartdoc generation process
71-
void initializeConfig(
72-
{Directory inputDir,
73-
String sdkVersion,
74-
bool showWarnings: false,
75-
bool addCrossdart: false,
76-
String examplePathPrefix,
77-
bool includeSource: true,
78-
bool autoIncludeDependencies: false}) {
79-
setConfig(
80-
inputDir: inputDir,
81-
sdkVersion: sdkVersion,
82-
showWarnings: showWarnings,
83-
addCrossdart: addCrossdart,
84-
examplePathPrefix: examplePathPrefix,
85-
includeSource: includeSource,
86-
autoIncludeDependencies: autoIncludeDependencies);
87-
}
88-
8972
Map<String, List<fileSystem.Folder>> _calculatePackageMap(
9073
fileSystem.Folder dir) {
9174
Map<String, List<fileSystem.Folder>> map = new Map();
@@ -125,7 +108,7 @@ class DartDoc {
125108
///
126109
/// [DartDocResults] is returned if dartdoc succeeds. [DartDocFailure] is
127110
/// thrown if dartdoc fails in an expected way, for example if there is an
128-
/// anaysis error in the code. Any other exception can be throw if there is an
111+
/// analysis error in the code. Any other exception can be throw if there is an
129112
/// unexpected failure.
130113
Future<DartDocResults> generateDocs() async {
131114
_stopwatch = new Stopwatch()..start();

lib/src/config.dart

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,27 @@
44

55
library dartdoc.config;
66

7+
import 'dart:collection' show UnmodifiableListView;
78
import 'dart:io';
89

910
class Config {
1011
final Directory inputDir;
11-
final bool addCrossdart;
1212
final bool showWarnings;
13+
final bool addCrossdart;
1314
final String examplePathPrefix;
1415
final bool includeSource;
1516
final String sdkVersion;
1617
final bool autoIncludeDependencies;
18+
final List<String> categoryOrder;
1719
Config._(
1820
this.inputDir,
1921
this.showWarnings,
2022
this.addCrossdart,
2123
this.examplePathPrefix,
2224
this.includeSource,
2325
this.sdkVersion,
24-
this.autoIncludeDependencies);
26+
this.autoIncludeDependencies,
27+
this.categoryOrder);
2528
}
2629

2730
Config _config;
@@ -30,11 +33,22 @@ Config get config => _config;
3033
void setConfig(
3134
{Directory inputDir,
3235
bool showWarnings: false,
33-
String sdkVersion,
3436
bool addCrossdart: false,
3537
String examplePathPrefix,
3638
bool includeSource: true,
37-
bool autoIncludeDependencies: false}) {
38-
_config = new Config._(inputDir, showWarnings, addCrossdart,
39-
examplePathPrefix, includeSource, sdkVersion, autoIncludeDependencies);
39+
String sdkVersion,
40+
bool autoIncludeDependencies: false,
41+
List<String> categoryOrder}) {
42+
if (categoryOrder == null) {
43+
categoryOrder = new UnmodifiableListView<String>([]);
44+
}
45+
_config = new Config._(
46+
inputDir,
47+
showWarnings,
48+
addCrossdart,
49+
examplePathPrefix,
50+
includeSource,
51+
sdkVersion,
52+
autoIncludeDependencies,
53+
categoryOrder);
4054
}

lib/src/html/html_generator_instance.dart

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -213,10 +213,10 @@ class HtmlGeneratorInstance implements HtmlOptions {
213213
_templates.constructorTemplate, data);
214214
}
215215

216-
void generateEnum(Package package, Library lib, Class eNum) {
216+
void generateEnum(Package package, Library lib, Enum eNum) {
217217
TemplateData data = new EnumTemplateData(this, package, lib, eNum);
218218

219-
_build(path.joinAll(eNum.href.split('/')), _templates.classTemplate, data);
219+
_build(path.joinAll(eNum.href.split('/')), _templates.enumTemplate, data);
220220
}
221221

222222
void generateFunction(Package package, Library lib, ModelFunction function) {

lib/src/html/template_data.dart

Lines changed: 23 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -119,17 +119,17 @@ class LibraryTemplateData extends TemplateData<Library> {
119119
List get navLinks => [package];
120120
@override
121121
Iterable<Subnav> getSubNavItems() sync* {
122+
if (library.hasClasses)
123+
yield new Subnav('Classes', '${library.href}#classes');
122124
if (library.hasConstants)
123125
yield new Subnav('Constants', '${library.href}#constants');
124-
if (library.hasTypedefs)
125-
yield new Subnav('Typedefs', '${library.href}#typedefs');
126126
if (library.hasProperties)
127127
yield new Subnav('Properties', '${library.href}#properties');
128128
if (library.hasFunctions)
129129
yield new Subnav('Functions', '${library.href}#functions');
130130
if (library.hasEnums) yield new Subnav('Enums', '${library.href}#enums');
131-
if (library.hasClasses)
132-
yield new Subnav('Classes', '${library.href}#classes');
131+
if (library.hasTypedefs)
132+
yield new Subnav('Typedefs', '${library.href}#typedefs');
133133
if (library.hasExceptions)
134134
yield new Subnav('Exceptions', '${library.href}#exceptions');
135135
}
@@ -171,20 +171,20 @@ class ClassTemplateData extends TemplateData<Class> {
171171
String get htmlBase => '..';
172172
@override
173173
Iterable<Subnav> getSubNavItems() sync* {
174-
if (clazz.hasConstants)
175-
yield new Subnav('Constants', '${clazz.href}#constants');
176-
if (clazz.hasStaticProperties)
177-
yield new Subnav('Static Properties', '${clazz.href}#static-properties');
178-
if (clazz.hasStaticMethods)
179-
yield new Subnav('Static Methods', '${clazz.href}#static-methods');
180-
if (clazz.hasProperties)
181-
yield new Subnav('Properties', '${clazz.href}#instance-properties');
182174
if (clazz.hasConstructors)
183175
yield new Subnav('Constructors', '${clazz.href}#constructors');
184-
if (clazz.hasOperators)
185-
yield new Subnav('Operators', '${clazz.href}#operators');
176+
if (clazz.hasProperties)
177+
yield new Subnav('Properties', '${clazz.href}#instance-properties');
186178
if (clazz.hasMethods)
187179
yield new Subnav('Methods', '${clazz.href}#instance-methods');
180+
if (clazz.hasOperators)
181+
yield new Subnav('Operators', '${clazz.href}#operators');
182+
if (clazz.hasStaticProperties)
183+
yield new Subnav('Static Properties', '${clazz.href}#static-properties');
184+
if (clazz.hasStaticMethods)
185+
yield new Subnav('Static Methods', '${clazz.href}#static-methods');
186+
if (clazz.hasConstants)
187+
yield new Subnav('Constants', '${clazz.href}#constants');
188188
}
189189

190190
Class get objectType {
@@ -235,30 +235,31 @@ class ConstructorTemplateData extends TemplateData<Constructor> {
235235

236236
class EnumTemplateData extends TemplateData<Enum> {
237237
EnumTemplateData(
238-
HtmlOptions htmlOptions, Package package, this.library, this.clazz)
238+
HtmlOptions htmlOptions, Package package, this.library, this.eNum)
239239
: super(htmlOptions, package);
240240

241241
final Library library;
242-
final Enum clazz;
242+
final Enum eNum;
243243
@override
244-
Enum get self => clazz;
244+
Enum get self => eNum;
245245
@override
246-
String get layoutTitle =>
247-
_layoutTitle(clazz.name, 'enum', clazz.isDeprecated);
246+
String get layoutTitle => _layoutTitle(eNum.name, 'enum', eNum.isDeprecated);
248247
@override
249248
String get title => '${self.name} enum - ${library.name} library - Dart API';
250249
@override
251250
String get metaDescription =>
252-
'API docs for the ${clazz.name} enum from the ${library.name} library, '
251+
'API docs for the ${eNum.name} enum from the ${library.name} library, '
253252
'for the Dart programming language.';
254253
@override
255254
List get navLinks => [package, library];
256255
@override
257256
String get htmlBase => '..';
258257
@override
259258
Iterable<Subnav> getSubNavItems() => [
260-
new Subnav('Constants', '${clazz.href}#constants'),
261-
new Subnav('Properties', '${clazz.href}#properties')
259+
new Subnav('Constants', '${eNum.href}#constants'),
260+
new Subnav('Properties', '${eNum.href}#instance-properties'),
261+
new Subnav('Methods', '${eNum.href}#instance-methods'),
262+
new Subnav('Operators', '${eNum.href}#operators')
262263
];
263264
}
264265

lib/src/html/templates.dart

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ const _partials = const <String>[
2626
'documentation',
2727
'name_summary',
2828
'sidebar_for_class',
29+
'sidebar_for_enum',
2930
'source_code',
3031
'sidebar_for_library',
3132
'accessor_getter',
@@ -74,6 +75,7 @@ Future<String> _getTemplateFile(String templateFileName) =>
7475

7576
class Templates {
7677
final TemplateRenderer classTemplate;
78+
final TemplateRenderer enumTemplate;
7779
final TemplateRenderer constantTemplate;
7880
final TemplateRenderer constructorTemplate;
7981
final TemplateRenderer functionTemplate;
@@ -105,6 +107,7 @@ class Templates {
105107
var indexTemplate = await _loadTemplate('index.html');
106108
var libraryTemplate = await _loadTemplate('library.html');
107109
var classTemplate = await _loadTemplate('class.html');
110+
var enumTemplate = await _loadTemplate('enum.html');
108111
var functionTemplate = await _loadTemplate('function.html');
109112
var methodTemplate = await _loadTemplate('method.html');
110113
var constructorTemplate = await _loadTemplate('constructor.html');
@@ -120,6 +123,7 @@ class Templates {
120123
indexTemplate,
121124
libraryTemplate,
122125
classTemplate,
126+
enumTemplate,
123127
functionTemplate,
124128
methodTemplate,
125129
constructorTemplate,
@@ -134,6 +138,7 @@ class Templates {
134138
this.indexTemplate,
135139
this.libraryTemplate,
136140
this.classTemplate,
141+
this.enumTemplate,
137142
this.functionTemplate,
138143
this.methodTemplate,
139144
this.constructorTemplate,

0 commit comments

Comments
 (0)