Deprecate options.dart.

bin/dartdoc.dart

@@ -6,8 +6,8 @@ library dartdoc.bin;
 
 import 'dart:async';
 
-import 'package:dartdoc/options.dart';
 import 'package:dartdoc/src/dartdoc.dart';
+import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/package_config_provider.dart';
 import 'package:dartdoc/src/package_meta.dart';

lib/options.dart

@@ -1,153 +1,7 @@
-import 'dart:io' show stderr, exitCode;
+// Copyright (c) 2023, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
 
-import 'package:args/args.dart';
-import 'package:dartdoc/src/dartdoc.dart' show dartdocVersion, programName;
-import 'package:dartdoc/src/dartdoc_options.dart';
-import 'package:dartdoc/src/generator/generator.dart';
-import 'package:dartdoc/src/logging.dart';
-import 'package:dartdoc/src/package_meta.dart';
-
-/// Helper class that consolidates option contexts for instantiating generators.
-class DartdocGeneratorOptionContext extends DartdocOptionContext {
-  DartdocGeneratorOptionContext(
-      super.optionSet, super.dir, super.resourceProvider);
-  DartdocGeneratorOptionContext.fromDefaultContextLocation(
-      super.optionSet, super.resourceProvider)
-      : super.fromDefaultContextLocation();
-
-  /// The joined contents of any 'header' files specified in options.
-  String get header =>
-      _joinCustomTextFiles(optionSet['header'].valueAt(context));
-
-  /// The joined contents of any 'footer' files specified in options.
-  String get footer =>
-      _joinCustomTextFiles(optionSet['footer'].valueAt(context));
-
-  /// The joined contents of any 'footer-text' files specified in options.
-  String get footerText =>
-      _joinCustomTextFiles(optionSet['footerText'].valueAt(context));
-
-  String _joinCustomTextFiles(Iterable<String> paths) => paths
-      .map((p) => resourceProvider.getFile(p).readAsStringSync())
-      .join('\n');
-
-  bool get prettyIndexJson => optionSet['prettyIndexJson'].valueAt(context);
-
-  String? get favicon => optionSet['favicon'].valueAt(context);
-
-  String? get relCanonicalPrefix =>
-      optionSet['relCanonicalPrefix'].valueAt(context);
-
-  String? get templatesDir => optionSet['templatesDir'].valueAt(context);
-
-  // TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration.
-  @override
-  bool get useBaseHref => optionSet['useBaseHref'].valueAt(context);
-
-  String? get resourcesDir => optionSet['resourcesDir'].valueAt(context);
-}
-
-class DartdocProgramOptionContext extends DartdocGeneratorOptionContext
-    with LoggingContext {
-  DartdocProgramOptionContext(
-      super.optionSet, super.dir, super.resourceProvider);
-
-  DartdocProgramOptionContext.fromDefaultContextLocation(
-      super.optionSet, super.resourceProvider)
-      : super.fromDefaultContextLocation();
-
-  /// Whether to generate docs or perform a dry run.
-  bool get generateDocs => optionSet['generateDocs'].valueAt(context);
-  bool get help => optionSet['help'].valueAt(context);
-  bool get version => optionSet['version'].valueAt(context);
-}
-
-List<DartdocOption<bool>> createDartdocProgramOptions(
-    PackageMetaProvider packageMetaProvider) {
-  var resourceProvider = packageMetaProvider.resourceProvider;
-  return [
-    DartdocOptionArgOnly<bool>('generateDocs', true, resourceProvider,
-        help:
-            'Generate docs into the output directory (or only display warnings '
-            'if false).',
-        negatable: true),
-    DartdocOptionArgOnly<bool>('help', false, resourceProvider,
-        abbr: 'h', help: 'Show command help.', negatable: false),
-    DartdocOptionArgOnly<bool>('version', false, resourceProvider,
-        help: 'Display the version for $programName.', negatable: false),
-  ];
-}
-
-DartdocProgramOptionContext? parseOptions(
-  PackageMetaProvider packageMetaProvider,
-  List<String> arguments, {
-  // Additional options are given in google3.
-  OptionGenerator? additionalOptions,
-}) {
-  var optionRoot = DartdocOptionRoot.fromOptionGenerators(
-      'dartdoc',
-      [
-        createDartdocOptions,
-        createDartdocProgramOptions,
-        createLoggingOptions,
-        createGeneratorOptions,
-        if (additionalOptions != null) additionalOptions,
-      ],
-      packageMetaProvider);
-
-  try {
-    optionRoot.parseArguments(arguments);
-  } on FormatException catch (e) {
-    stderr.writeln(' fatal error: ${e.message}');
-    stderr.writeln('');
-    _printUsage(optionRoot.argParser);
-    // Do not use `exit()` as this bypasses `--pause-isolates-on-exit`.
-    exitCode = 64;
-    return null;
-  }
-  if (optionRoot['help'].valueAtCurrent() as bool) {
-    _printHelp(optionRoot.argParser);
-    exitCode = 0;
-    return null;
-  }
-  if (optionRoot['version'].valueAtCurrent() as bool) {
-    _printVersion(optionRoot.argParser);
-    exitCode = 0;
-    return null;
-  }
-
-  DartdocProgramOptionContext config;
-  try {
-    config = DartdocProgramOptionContext.fromDefaultContextLocation(
-        optionRoot, packageMetaProvider.resourceProvider);
-  } on DartdocOptionError catch (e) {
-    stderr.writeln(' fatal error: ${e.message}');
-    stderr.writeln('');
-    _printUsage(optionRoot.argParser);
-    exitCode = 64;
-    return null;
-  }
-  startLogging(
-    isJson: config.json,
-    isQuiet: config.quiet,
-    showProgress: config.showProgress,
-  );
-  return config;
-}
-
-/// Print help if we are passed the help option.
-void _printHelp(ArgParser parser) {
-  print('Generate HTML documentation for Dart libraries.\n');
-  print(parser.usage);
-}
-
-/// Print usage information on invalid command lines.
-void _printUsage(ArgParser parser) {
-  print('Usage: dartdoc [OPTIONS]\n');
-  print(parser.usage);
-}
-
-/// Print version information.
-void _printVersion(ArgParser parser) {
-  print('dartdoc version: $dartdocVersion');
-}
+@Deprecated(
+    'Will be removed in a later version of DartDoc. Use /src/dartdoc_options.dart.')
+export 'package:dartdoc/src/dartdoc_options.dart';

lib/src/dartdoc.dart

@@ -7,7 +7,6 @@ import 'dart:convert';
 import 'dart:io' show Platform, exitCode, stderr;
 
 import 'package:analyzer/file_system/file_system.dart';
-import 'package:dartdoc/options.dart';
 import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/failure.dart';
 import 'package:dartdoc/src/generator/empty_generator.dart';

lib/src/dartdoc_options.dart

@@ -14,14 +14,17 @@
 ///
 library dartdoc.dartdoc_options;
 
-import 'dart:io' show Platform, stdout;
+import 'dart:io' show Platform, exitCode, stderr, stdout;
 
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/file_system/file_system.dart';
 import 'package:args/args.dart';
+import 'package:dartdoc/src/dartdoc.dart' show dartdocVersion, programName;
 import 'package:dartdoc/src/experiment_options.dart';
 import 'package:dartdoc/src/failure.dart';
+import 'package:dartdoc/src/generator/generator.dart';
 import 'package:dartdoc/src/io_utils.dart';
+import 'package:dartdoc/src/logging.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/package_meta.dart';
 import 'package:dartdoc/src/source_linker.dart';
@@ -1340,6 +1343,151 @@ class DartdocOptionContext extends DartdocOptionContextBase
       int.parse(optionSet['maxTotalSize'].valueAt(context) ?? '0');
 }
 
+/// Helper class that consolidates option contexts for instantiating generators.
+class DartdocGeneratorOptionContext extends DartdocOptionContext {
+  DartdocGeneratorOptionContext(
+      super.optionSet, super.dir, super.resourceProvider);
+  DartdocGeneratorOptionContext.fromDefaultContextLocation(
+      super.optionSet, super.resourceProvider)
+      : super.fromDefaultContextLocation();
+
+  /// The joined contents of any 'header' files specified in options.
+  String get header =>
+      _joinCustomTextFiles(optionSet['header'].valueAt(context));
+
+  /// The joined contents of any 'footer' files specified in options.
+  String get footer =>
+      _joinCustomTextFiles(optionSet['footer'].valueAt(context));
+
+  /// The joined contents of any 'footer-text' files specified in options.
+  String get footerText =>
+      _joinCustomTextFiles(optionSet['footerText'].valueAt(context));
+
+  String _joinCustomTextFiles(Iterable<String> paths) => paths
+      .map((p) => resourceProvider.getFile(p).readAsStringSync())
+      .join('\n');
+
+  bool get prettyIndexJson => optionSet['prettyIndexJson'].valueAt(context);
+
+  String? get favicon => optionSet['favicon'].valueAt(context);
+
+  String? get relCanonicalPrefix =>
+      optionSet['relCanonicalPrefix'].valueAt(context);
+
+  String? get templatesDir => optionSet['templatesDir'].valueAt(context);
+
+  // TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration.
+  @override
+  bool get useBaseHref => optionSet['useBaseHref'].valueAt(context);
+
+  String? get resourcesDir => optionSet['resourcesDir'].valueAt(context);
+}
+
+class DartdocProgramOptionContext extends DartdocGeneratorOptionContext
+    with LoggingContext {
+  DartdocProgramOptionContext(
+      super.optionSet, super.dir, super.resourceProvider);
+
+  DartdocProgramOptionContext.fromDefaultContextLocation(
+      super.optionSet, super.resourceProvider)
+      : super.fromDefaultContextLocation();
+
+  /// Whether to generate docs or perform a dry run.
+  bool get generateDocs => optionSet['generateDocs'].valueAt(context);
+  bool get help => optionSet['help'].valueAt(context);
+  bool get version => optionSet['version'].valueAt(context);
+}
+
+List<DartdocOption<bool>> createDartdocProgramOptions(
+    PackageMetaProvider packageMetaProvider) {
+  var resourceProvider = packageMetaProvider.resourceProvider;
+  return [
+    DartdocOptionArgOnly<bool>('generateDocs', true, resourceProvider,
+        help:
+            'Generate docs into the output directory (or only display warnings '
+            'if false).',
+        negatable: true),
+    DartdocOptionArgOnly<bool>('help', false, resourceProvider,
+        abbr: 'h', help: 'Show command help.', negatable: false),
+    DartdocOptionArgOnly<bool>('version', false, resourceProvider,
+        help: 'Display the version for $programName.', negatable: false),
+  ];
+}
+
+DartdocProgramOptionContext? parseOptions(
+  PackageMetaProvider packageMetaProvider,
+  List<String> arguments, {
+  // Additional options are given in google3.
+  OptionGenerator? additionalOptions,
+}) {
+  var optionRoot = DartdocOptionRoot.fromOptionGenerators(
+      'dartdoc',
+      [
+        createDartdocOptions,
+        createDartdocProgramOptions,
+        createLoggingOptions,
+        createGeneratorOptions,
+        if (additionalOptions != null) additionalOptions,
+      ],
+      packageMetaProvider);
+
+  try {
+    optionRoot.parseArguments(arguments);
+  } on FormatException catch (e) {
+    stderr.writeln(' fatal error: ${e.message}');
+    stderr.writeln('');
+    _printUsage(optionRoot.argParser);
+    // Do not use `exit()` as this bypasses `--pause-isolates-on-exit`.
+    exitCode = 64;
+    return null;
+  }
+  if (optionRoot['help'].valueAtCurrent() as bool) {
+    _printHelp(optionRoot.argParser);
+    exitCode = 0;
+    return null;
+  }
+  if (optionRoot['version'].valueAtCurrent() as bool) {
+    _printVersion(optionRoot.argParser);
+    exitCode = 0;
+    return null;
+  }
+
+  DartdocProgramOptionContext config;
+  try {
+    config = DartdocProgramOptionContext.fromDefaultContextLocation(
+        optionRoot, packageMetaProvider.resourceProvider);
+  } on DartdocOptionError catch (e) {
+    stderr.writeln(' fatal error: ${e.message}');
+    stderr.writeln('');
+    _printUsage(optionRoot.argParser);
+    exitCode = 64;
+    return null;
+  }
+  startLogging(
+    isJson: config.json,
+    isQuiet: config.quiet,
+    showProgress: config.showProgress,
+  );
+  return config;
+}
+
+/// Print help if we are passed the help option.
+void _printHelp(ArgParser parser) {
+  print('Generate HTML documentation for Dart libraries.\n');
+  print(parser.usage);
+}
+
+/// Print usage information on invalid command lines.
+void _printUsage(ArgParser parser) {
+  print('Usage: dartdoc [OPTIONS]\n');
+  print(parser.usage);
+}
+
+/// Print version information.
+void _printVersion(ArgParser parser) {
+  print('dartdoc version: $dartdocVersion');
+}
+
 /// Instantiate dartdoc's configuration file and options parser with the
 /// given command line arguments.
 List<DartdocOption> createDartdocOptions(

lib/src/generator/generator_backend.dart

@@ -3,7 +3,7 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'package:analyzer/file_system/file_system.dart';
-import 'package:dartdoc/options.dart';
+import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/generator/generator.dart';
 import 'package:dartdoc/src/generator/generator_utils.dart' as generator_util;
 import 'package:dartdoc/src/generator/template_data.dart';

lib/src/generator/html_generator.dart

@@ -4,7 +4,7 @@
 
 library dartdoc.html_generator;
 
-import 'package:dartdoc/options.dart';
+import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/generator/generator.dart';
 import 'package:dartdoc/src/generator/generator_backend.dart';
 import 'package:dartdoc/src/generator/generator_frontend.dart';

lib/src/generator/markdown_generator.dart

@@ -2,7 +2,7 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'package:dartdoc/options.dart';
+import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/generator/generator.dart';
 import 'package:dartdoc/src/generator/generator_backend.dart';
 import 'package:dartdoc/src/generator/generator_frontend.dart';

lib/src/generator/templates.dart

@@ -39,7 +39,7 @@
 library dartdoc.templates;
 
 import 'package:analyzer/file_system/file_system.dart';
-import 'package:dartdoc/options.dart';
+import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/element_type.dart';
 import 'package:dartdoc/src/failure.dart';
 import 'package:dartdoc/src/generator/resource_loader.dart';

test/end2end/dartdoc_test.dart

@@ -7,7 +7,6 @@ library dartdoc.dartdoc_test;
 import 'dart:async';
 
 import 'package:analyzer/file_system/file_system.dart';
-import 'package:dartdoc/options.dart';
 import 'package:dartdoc/src/dartdoc.dart' show Dartdoc, DartdocResults;
 import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/failure.dart';