Skip to content

Commit c78ec71

Browse files
kallentukallentu
authored
Deprecate options.dart. (#3591)
1 parent 0499c4e commit c78ec71

16 files changed

+163
-167
lines changed

‎bin/dartdoc.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ library dartdoc.bin;
66

77
import 'dart:async';
88

9-
import 'package:dartdoc/options.dart';
109
import 'package:dartdoc/src/dartdoc.dart';
10+
import 'package:dartdoc/src/dartdoc_options.dart';
1111
import 'package:dartdoc/src/model/model.dart';
1212
import 'package:dartdoc/src/package_config_provider.dart';
1313
import 'package:dartdoc/src/package_meta.dart';

‎lib/options.dart

Lines changed: 6 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -1,153 +1,7 @@
1-
import 'dart:io' show stderr, exitCode;
1+
// Copyright (c) 2023, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
24

3-
import 'package:args/args.dart';
4-
import 'package:dartdoc/src/dartdoc.dart' show dartdocVersion, programName;
5-
import 'package:dartdoc/src/dartdoc_options.dart';
6-
import 'package:dartdoc/src/generator/generator.dart';
7-
import 'package:dartdoc/src/logging.dart';
8-
import 'package:dartdoc/src/package_meta.dart';
9-
10-
/// Helper class that consolidates option contexts for instantiating generators.
11-
class DartdocGeneratorOptionContext extends DartdocOptionContext {
12-
DartdocGeneratorOptionContext(
13-
super.optionSet, super.dir, super.resourceProvider);
14-
DartdocGeneratorOptionContext.fromDefaultContextLocation(
15-
super.optionSet, super.resourceProvider)
16-
: super.fromDefaultContextLocation();
17-
18-
/// The joined contents of any 'header' files specified in options.
19-
String get header =>
20-
_joinCustomTextFiles(optionSet['header'].valueAt(context));
21-
22-
/// The joined contents of any 'footer' files specified in options.
23-
String get footer =>
24-
_joinCustomTextFiles(optionSet['footer'].valueAt(context));
25-
26-
/// The joined contents of any 'footer-text' files specified in options.
27-
String get footerText =>
28-
_joinCustomTextFiles(optionSet['footerText'].valueAt(context));
29-
30-
String _joinCustomTextFiles(Iterable<String> paths) => paths
31-
.map((p) => resourceProvider.getFile(p).readAsStringSync())
32-
.join('\n');
33-
34-
bool get prettyIndexJson => optionSet['prettyIndexJson'].valueAt(context);
35-
36-
String? get favicon => optionSet['favicon'].valueAt(context);
37-
38-
String? get relCanonicalPrefix =>
39-
optionSet['relCanonicalPrefix'].valueAt(context);
40-
41-
String? get templatesDir => optionSet['templatesDir'].valueAt(context);
42-
43-
// TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration.
44-
@override
45-
bool get useBaseHref => optionSet['useBaseHref'].valueAt(context);
46-
47-
String? get resourcesDir => optionSet['resourcesDir'].valueAt(context);
48-
}
49-
50-
class DartdocProgramOptionContext extends DartdocGeneratorOptionContext
51-
with LoggingContext {
52-
DartdocProgramOptionContext(
53-
super.optionSet, super.dir, super.resourceProvider);
54-
55-
DartdocProgramOptionContext.fromDefaultContextLocation(
56-
super.optionSet, super.resourceProvider)
57-
: super.fromDefaultContextLocation();
58-
59-
/// Whether to generate docs or perform a dry run.
60-
bool get generateDocs => optionSet['generateDocs'].valueAt(context);
61-
bool get help => optionSet['help'].valueAt(context);
62-
bool get version => optionSet['version'].valueAt(context);
63-
}
64-
65-
List<DartdocOption<bool>> createDartdocProgramOptions(
66-
PackageMetaProvider packageMetaProvider) {
67-
var resourceProvider = packageMetaProvider.resourceProvider;
68-
return [
69-
DartdocOptionArgOnly<bool>('generateDocs', true, resourceProvider,
70-
help:
71-
'Generate docs into the output directory (or only display warnings '
72-
'if false).',
73-
negatable: true),
74-
DartdocOptionArgOnly<bool>('help', false, resourceProvider,
75-
abbr: 'h', help: 'Show command help.', negatable: false),
76-
DartdocOptionArgOnly<bool>('version', false, resourceProvider,
77-
help: 'Display the version for $programName.', negatable: false),
78-
];
79-
}
80-
81-
DartdocProgramOptionContext? parseOptions(
82-
PackageMetaProvider packageMetaProvider,
83-
List<String> arguments, {
84-
// Additional options are given in google3.
85-
OptionGenerator? additionalOptions,
86-
}) {
87-
var optionRoot = DartdocOptionRoot.fromOptionGenerators(
88-
'dartdoc',
89-
[
90-
createDartdocOptions,
91-
createDartdocProgramOptions,
92-
createLoggingOptions,
93-
createGeneratorOptions,
94-
if (additionalOptions != null) additionalOptions,
95-
],
96-
packageMetaProvider);
97-
98-
try {
99-
optionRoot.parseArguments(arguments);
100-
} on FormatException catch (e) {
101-
stderr.writeln(' fatal error: ${e.message}');
102-
stderr.writeln('');
103-
_printUsage(optionRoot.argParser);
104-
// Do not use `exit()` as this bypasses `--pause-isolates-on-exit`.
105-
exitCode = 64;
106-
return null;
107-
}
108-
if (optionRoot['help'].valueAtCurrent() as bool) {
109-
_printHelp(optionRoot.argParser);
110-
exitCode = 0;
111-
return null;
112-
}
113-
if (optionRoot['version'].valueAtCurrent() as bool) {
114-
_printVersion(optionRoot.argParser);
115-
exitCode = 0;
116-
return null;
117-
}
118-
119-
DartdocProgramOptionContext config;
120-
try {
121-
config = DartdocProgramOptionContext.fromDefaultContextLocation(
122-
optionRoot, packageMetaProvider.resourceProvider);
123-
} on DartdocOptionError catch (e) {
124-
stderr.writeln(' fatal error: ${e.message}');
125-
stderr.writeln('');
126-
_printUsage(optionRoot.argParser);
127-
exitCode = 64;
128-
return null;
129-
}
130-
startLogging(
131-
isJson: config.json,
132-
isQuiet: config.quiet,
133-
showProgress: config.showProgress,
134-
);
135-
return config;
136-
}
137-
138-
/// Print help if we are passed the help option.
139-
void _printHelp(ArgParser parser) {
140-
print('Generate HTML documentation for Dart libraries.\n');
141-
print(parser.usage);
142-
}
143-
144-
/// Print usage information on invalid command lines.
145-
void _printUsage(ArgParser parser) {
146-
print('Usage: dartdoc [OPTIONS]\n');
147-
print(parser.usage);
148-
}
149-
150-
/// Print version information.
151-
void _printVersion(ArgParser parser) {
152-
print('dartdoc version: $dartdocVersion');
153-
}
5+
@Deprecated(
6+
'Will be removed in a later version of DartDoc. Use /src/dartdoc_options.dart.')
7+
export 'package:dartdoc/src/dartdoc_options.dart';

‎lib/src/dartdoc.dart

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ import 'dart:convert';
77
import 'dart:io' show Platform, exitCode, stderr;
88

99
import 'package:analyzer/file_system/file_system.dart';
10-
import 'package:dartdoc/options.dart';
1110
import 'package:dartdoc/src/dartdoc_options.dart';
1211
import 'package:dartdoc/src/failure.dart';
1312
import 'package:dartdoc/src/generator/empty_generator.dart';

‎lib/src/dartdoc_options.dart

Lines changed: 149 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,17 @@
1414
///
1515
library dartdoc.dartdoc_options;
1616

17-
import 'dart:io' show Platform, stdout;
17+
import 'dart:io' show Platform, exitCode, stderr, stdout;
1818

1919
import 'package:analyzer/dart/element/element.dart';
2020
import 'package:analyzer/file_system/file_system.dart';
2121
import 'package:args/args.dart';
22+
import 'package:dartdoc/src/dartdoc.dart' show dartdocVersion, programName;
2223
import 'package:dartdoc/src/experiment_options.dart';
2324
import 'package:dartdoc/src/failure.dart';
25+
import 'package:dartdoc/src/generator/generator.dart';
2426
import 'package:dartdoc/src/io_utils.dart';
27+
import 'package:dartdoc/src/logging.dart';
2528
import 'package:dartdoc/src/model/model.dart';
2629
import 'package:dartdoc/src/package_meta.dart';
2730
import 'package:dartdoc/src/source_linker.dart';
@@ -1340,6 +1343,151 @@ class DartdocOptionContext extends DartdocOptionContextBase
13401343
int.parse(optionSet['maxTotalSize'].valueAt(context) ?? '0');
13411344
}
13421345

1346+
/// Helper class that consolidates option contexts for instantiating generators.
1347+
class DartdocGeneratorOptionContext extends DartdocOptionContext {
1348+
DartdocGeneratorOptionContext(
1349+
super.optionSet, super.dir, super.resourceProvider);
1350+
DartdocGeneratorOptionContext.fromDefaultContextLocation(
1351+
super.optionSet, super.resourceProvider)
1352+
: super.fromDefaultContextLocation();
1353+
1354+
/// The joined contents of any 'header' files specified in options.
1355+
String get header =>
1356+
_joinCustomTextFiles(optionSet['header'].valueAt(context));
1357+
1358+
/// The joined contents of any 'footer' files specified in options.
1359+
String get footer =>
1360+
_joinCustomTextFiles(optionSet['footer'].valueAt(context));
1361+
1362+
/// The joined contents of any 'footer-text' files specified in options.
1363+
String get footerText =>
1364+
_joinCustomTextFiles(optionSet['footerText'].valueAt(context));
1365+
1366+
String _joinCustomTextFiles(Iterable<String> paths) => paths
1367+
.map((p) => resourceProvider.getFile(p).readAsStringSync())
1368+
.join('\n');
1369+
1370+
bool get prettyIndexJson => optionSet['prettyIndexJson'].valueAt(context);
1371+
1372+
String? get favicon => optionSet['favicon'].valueAt(context);
1373+
1374+
String? get relCanonicalPrefix =>
1375+
optionSet['relCanonicalPrefix'].valueAt(context);
1376+
1377+
String? get templatesDir => optionSet['templatesDir'].valueAt(context);
1378+
1379+
// TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration.
1380+
@override
1381+
bool get useBaseHref => optionSet['useBaseHref'].valueAt(context);
1382+
1383+
String? get resourcesDir => optionSet['resourcesDir'].valueAt(context);
1384+
}
1385+
1386+
class DartdocProgramOptionContext extends DartdocGeneratorOptionContext
1387+
with LoggingContext {
1388+
DartdocProgramOptionContext(
1389+
super.optionSet, super.dir, super.resourceProvider);
1390+
1391+
DartdocProgramOptionContext.fromDefaultContextLocation(
1392+
super.optionSet, super.resourceProvider)
1393+
: super.fromDefaultContextLocation();
1394+
1395+
/// Whether to generate docs or perform a dry run.
1396+
bool get generateDocs => optionSet['generateDocs'].valueAt(context);
1397+
bool get help => optionSet['help'].valueAt(context);
1398+
bool get version => optionSet['version'].valueAt(context);
1399+
}
1400+
1401+
List<DartdocOption<bool>> createDartdocProgramOptions(
1402+
PackageMetaProvider packageMetaProvider) {
1403+
var resourceProvider = packageMetaProvider.resourceProvider;
1404+
return [
1405+
DartdocOptionArgOnly<bool>('generateDocs', true, resourceProvider,
1406+
help:
1407+
'Generate docs into the output directory (or only display warnings '
1408+
'if false).',
1409+
negatable: true),
1410+
DartdocOptionArgOnly<bool>('help', false, resourceProvider,
1411+
abbr: 'h', help: 'Show command help.', negatable: false),
1412+
DartdocOptionArgOnly<bool>('version', false, resourceProvider,
1413+
help: 'Display the version for $programName.', negatable: false),
1414+
];
1415+
}
1416+
1417+
DartdocProgramOptionContext? parseOptions(
1418+
PackageMetaProvider packageMetaProvider,
1419+
List<String> arguments, {
1420+
// Additional options are given in google3.
1421+
OptionGenerator? additionalOptions,
1422+
}) {
1423+
var optionRoot = DartdocOptionRoot.fromOptionGenerators(
1424+
'dartdoc',
1425+
[
1426+
createDartdocOptions,
1427+
createDartdocProgramOptions,
1428+
createLoggingOptions,
1429+
createGeneratorOptions,
1430+
if (additionalOptions != null) additionalOptions,
1431+
],
1432+
packageMetaProvider);
1433+
1434+
try {
1435+
optionRoot.parseArguments(arguments);
1436+
} on FormatException catch (e) {
1437+
stderr.writeln(' fatal error: ${e.message}');
1438+
stderr.writeln('');
1439+
_printUsage(optionRoot.argParser);
1440+
// Do not use `exit()` as this bypasses `--pause-isolates-on-exit`.
1441+
exitCode = 64;
1442+
return null;
1443+
}
1444+
if (optionRoot['help'].valueAtCurrent() as bool) {
1445+
_printHelp(optionRoot.argParser);
1446+
exitCode = 0;
1447+
return null;
1448+
}
1449+
if (optionRoot['version'].valueAtCurrent() as bool) {
1450+
_printVersion(optionRoot.argParser);
1451+
exitCode = 0;
1452+
return null;
1453+
}
1454+
1455+
DartdocProgramOptionContext config;
1456+
try {
1457+
config = DartdocProgramOptionContext.fromDefaultContextLocation(
1458+
optionRoot, packageMetaProvider.resourceProvider);
1459+
} on DartdocOptionError catch (e) {
1460+
stderr.writeln(' fatal error: ${e.message}');
1461+
stderr.writeln('');
1462+
_printUsage(optionRoot.argParser);
1463+
exitCode = 64;
1464+
return null;
1465+
}
1466+
startLogging(
1467+
isJson: config.json,
1468+
isQuiet: config.quiet,
1469+
showProgress: config.showProgress,
1470+
);
1471+
return config;
1472+
}
1473+
1474+
/// Print help if we are passed the help option.
1475+
void _printHelp(ArgParser parser) {
1476+
print('Generate HTML documentation for Dart libraries.\n');
1477+
print(parser.usage);
1478+
}
1479+
1480+
/// Print usage information on invalid command lines.
1481+
void _printUsage(ArgParser parser) {
1482+
print('Usage: dartdoc [OPTIONS]\n');
1483+
print(parser.usage);
1484+
}
1485+
1486+
/// Print version information.
1487+
void _printVersion(ArgParser parser) {
1488+
print('dartdoc version: $dartdocVersion');
1489+
}
1490+
13431491
/// Instantiate dartdoc's configuration file and options parser with the
13441492
/// given command line arguments.
13451493
List<DartdocOption> createDartdocOptions(

‎lib/src/generator/generator_backend.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
// BSD-style license that can be found in the LICENSE file.
44

55
import 'package:analyzer/file_system/file_system.dart';
6-
import 'package:dartdoc/options.dart';
6+
import 'package:dartdoc/src/dartdoc_options.dart';
77
import 'package:dartdoc/src/generator/generator.dart';
88
import 'package:dartdoc/src/generator/generator_utils.dart' as generator_util;
99
import 'package:dartdoc/src/generator/template_data.dart';

‎lib/src/generator/html_generator.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
library dartdoc.html_generator;
66

7-
import 'package:dartdoc/options.dart';
7+
import 'package:dartdoc/src/dartdoc_options.dart';
88
import 'package:dartdoc/src/generator/generator.dart';
99
import 'package:dartdoc/src/generator/generator_backend.dart';
1010
import 'package:dartdoc/src/generator/generator_frontend.dart';

‎lib/src/generator/markdown_generator.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
// for details. All rights reserved. Use of this source code is governed by a
33
// BSD-style license that can be found in the LICENSE file.
44

5-
import 'package:dartdoc/options.dart';
5+
import 'package:dartdoc/src/dartdoc_options.dart';
66
import 'package:dartdoc/src/generator/generator.dart';
77
import 'package:dartdoc/src/generator/generator_backend.dart';
88
import 'package:dartdoc/src/generator/generator_frontend.dart';

‎lib/src/generator/templates.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
library dartdoc.templates;
4040

4141
import 'package:analyzer/file_system/file_system.dart';
42-
import 'package:dartdoc/options.dart';
42+
import 'package:dartdoc/src/dartdoc_options.dart';
4343
import 'package:dartdoc/src/element_type.dart';
4444
import 'package:dartdoc/src/failure.dart';
4545
import 'package:dartdoc/src/generator/resource_loader.dart';

‎test/end2end/dartdoc_test.dart

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ library dartdoc.dartdoc_test;
77
import 'dart:async';
88

99
import 'package:analyzer/file_system/file_system.dart';
10-
import 'package:dartdoc/options.dart';
1110
import 'package:dartdoc/src/dartdoc.dart' show Dartdoc, DartdocResults;
1211
import 'package:dartdoc/src/dartdoc_options.dart';
1312
import 'package:dartdoc/src/failure.dart';

0 commit comments

Comments
 (0)