Allow dartdoc to customize package builder and package meta creation (#2209)

Author: mehmetf

bin/dartdoc.dart

@@ -5,134 +5,27 @@
 library dartdoc.bin;
 
 import 'dart:async';
-import 'dart:io';
 
-import 'package:args/args.dart';
 import 'package:dartdoc/dartdoc.dart';
-import 'package:dartdoc/src/logging.dart';
-import 'package:dartdoc/src/tool_runner.dart';
-import 'package:stack_trace/stack_trace.dart';
-
-class DartdocProgramOptionContext extends DartdocGeneratorOptionContext
-    with LoggingContext {
-  DartdocProgramOptionContext(DartdocOptionSet optionSet, Directory dir)
-      : super(optionSet, dir);
-
-  bool get asyncStackTraces => optionSet['asyncStackTraces'].valueAt(context);
-  bool get generateDocs => optionSet['generateDocs'].valueAt(context);
-  bool get help => optionSet['help'].valueAt(context);
-  bool get version => optionSet['version'].valueAt(context);
-}
-
-Future<List<DartdocOption>> createDartdocProgramOptions() async {
-  return <DartdocOption>[
-    DartdocOptionArgOnly<bool>('asyncStackTraces', false,
-        help: 'Display coordinated asynchronous stack traces (slow)',
-        negatable: true),
-    DartdocOptionArgOnly<bool>('generateDocs', true,
-        help:
-            'Generate docs into the output directory (or only display warnings if false).',
-        negatable: true),
-    DartdocOptionArgOnly<bool>('help', false,
-        abbr: 'h', help: 'Show command help.', negatable: false),
-    DartdocOptionArgOnly<bool>('version', false,
-        help: 'Display the version for $programName.', negatable: false),
-  ];
-}
+import 'package:dartdoc/options.dart';
 
 /// Analyzes Dart files and generates a representation of included libraries,
 /// classes, and members. Uses the current directory to look for libraries.
 Future<void> main(List<String> arguments) async {
-  var optionSet = await DartdocOptionSet.fromOptionGenerators('dartdoc', [
-    createDartdocOptions,
-    createDartdocProgramOptions,
-    createLoggingOptions,
-    createGeneratorOptions,
-  ]);
-
-  try {
-    optionSet.parseArguments(arguments);
-  } on FormatException catch (e) {
-    stderr.writeln(' fatal error: ${e.message}');
-    stderr.writeln('');
-    _printUsage(optionSet.argParser);
-    // Do not use exit() as this bypasses --pause-isolates-on-exit
-    // TODO(jcollins-g): use exit once dart-lang/sdk#31747 is fixed.
-    exitCode = 64;
+  var config = await parseOptions(arguments);
+  if (config == null) {
+    // There was an error while parsing options.
     return;
   }
-  if (optionSet['help'].valueAt(Directory.current)) {
-    _printHelp(optionSet.argParser);
-    exitCode = 0;
-    return;
-  }
-  if (optionSet['version'].valueAt(Directory.current)) {
-    _printVersion(optionSet.argParser);
-    exitCode = 0;
-    return;
-  }
-
-  DartdocProgramOptionContext config;
-  try {
-    config = DartdocProgramOptionContext(optionSet, null);
-  } on DartdocOptionError catch (e) {
-    stderr.writeln(' fatal error: ${e.message}');
-    stderr.writeln('');
-    await stderr.flush();
-    _printUsage(optionSet.argParser);
-    exitCode = 64;
-    return;
-  }
-  startLogging(config);
-
-  var dartdoc = config.generateDocs
-      ? await Dartdoc.fromContext(config)
-      : await Dartdoc.withEmptyGenerator(config);
-  dartdoc.onCheckProgress.listen(logProgress);
-  try {
-    await Chain.capture(() async {
-      await runZoned(dartdoc.generateDocs,
-          zoneSpecification: ZoneSpecification(
-              print: (Zone self, ZoneDelegate parent, Zone zone, String line) =>
-                  logPrint(line)));
-    }, onError: (e, Chain chain) {
-      if (e is DartdocFailure) {
-        stderr.writeln('\ndartdoc failed: ${e}.');
-        if (config.verboseWarnings) {
-          stderr.writeln(chain.terse);
-        }
-        exitCode = 1;
-        return;
-      } else {
-        stderr.writeln('\ndartdoc failed: ${e}\n${chain.terse}');
-        exitCode = 255;
-        return;
-      }
-    }, when: config.asyncStackTraces);
-  } finally {
-    // Clear out any cached tool snapshots and temporary directories.
-    // ignore: unawaited_futures
-    SnapshotCache.instance.dispose();
-    // ignore: unawaited_futures
-    ToolTempFileTracker.instance.dispose();
-  }
-  exitCode = 0;
-  return;
-}
-
-/// 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}');
+  // Set the default way to construct [PackageMeta].
+  PackageMeta.setPackageMetaFactories(
+    PubPackageMeta.fromElement,
+    PubPackageMeta.fromFilename,
+    PubPackageMeta.fromDir,
+  );
+  final packageBuilder = PubPackageBuilder(config);
+  final dartdoc = config.generateDocs
+      ? await Dartdoc.fromContext(config, packageBuilder)
+      : await Dartdoc.withEmptyGenerator(config, packageBuilder);
+  dartdoc.executeGuarded();
 }

lib/dartdoc.dart

@@ -20,6 +20,7 @@ import 'package:dartdoc/src/generator/markdown_generator.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/tool_runner.dart';
 import 'package:dartdoc/src/tuple.dart';
 import 'package:dartdoc/src/utils.dart';
 import 'package:dartdoc/src/version.dart';
@@ -94,36 +95,53 @@ class DartdocFileWriter implements FileWriter {
 
 /// Generates Dart documentation for all public Dart libraries in the given
 /// directory.
-class Dartdoc extends PackageBuilder {
+class Dartdoc {
   final Generator generator;
+  final PackageBuilder packageBuilder;
+  final DartdocOptionContext config;
   final Set<String> writtenFiles = {};
   Directory outputDir;
 
   // Fires when the self checks make progress.
   final StreamController<String> _onCheckProgress =
       StreamController(sync: true);
 
-  Dartdoc._(DartdocOptionContext config, this.generator) : super(config) {
+  Dartdoc._(this.config, this.generator, this.packageBuilder) {
     outputDir = Directory(config.output)..createSync(recursive: true);
   }
 
   /// An asynchronous factory method that builds Dartdoc's file writers
   /// and returns a Dartdoc object with them.
   @Deprecated('Prefer fromContext() instead')
   static Future<Dartdoc> withDefaultGenerators(
-      DartdocGeneratorOptionContext config) async {
-    return Dartdoc._(config, await initHtmlGenerator(config));
+    DartdocGeneratorOptionContext config,
+    PackageBuilder packageBuilder,
+  ) async {
+    return Dartdoc._(
+      config,
+      await initHtmlGenerator(config),
+      packageBuilder,
+    );
   }
 
   /// Asynchronous factory method that builds Dartdoc with an empty generator.
-  static Future<Dartdoc> withEmptyGenerator(DartdocOptionContext config) async {
-    return Dartdoc._(config, await initEmptyGenerator(config));
+  static Future<Dartdoc> withEmptyGenerator(
+    DartdocOptionContext config,
+    PackageBuilder packageBuilder,
+  ) async {
+    return Dartdoc._(
+      config,
+      await initEmptyGenerator(config),
+      packageBuilder,
+    );
   }
 
   /// Asynchronous factory method that builds Dartdoc with a generator
   /// determined by the given context.
   static Future<Dartdoc> fromContext(
-      DartdocGeneratorOptionContext context) async {
+    DartdocGeneratorOptionContext context,
+    PackageBuilder packageBuilder,
+  ) async {
     Generator generator;
     switch (context.format) {
       case 'html':
@@ -135,7 +153,11 @@ class Dartdoc extends PackageBuilder {
       default:
         throw DartdocFailure('Unsupported output format: ${context.format}');
     }
-    return Dartdoc._(context, generator);
+    return Dartdoc._(
+      context,
+      generator,
+      packageBuilder,
+    );
   }
 
   Stream<String> get onCheckProgress => _onCheckProgress.stream;
@@ -150,7 +172,7 @@ class Dartdoc extends PackageBuilder {
   Future<DartdocResults> generateDocsBase() async {
     var _stopwatch = Stopwatch()..start();
     double seconds;
-    packageGraph = await buildPackageGraph();
+    packageGraph = await packageBuilder.buildPackageGraph();
     seconds = _stopwatch.elapsedMilliseconds / 1000.0;
     var libs = packageGraph.libraries.length;
     logInfo("Initialized dartdoc with ${libs} librar${libs == 1 ? 'y' : 'ies'} "
@@ -188,22 +210,31 @@ class Dartdoc extends PackageBuilder {
   }
 
   Future<DartdocResults> generateDocs() async {
-    logInfo('Documenting ${config.topLevelPackageMeta}...');
+    try {
+      logInfo('Documenting ${config.topLevelPackageMeta}...');
 
-    var dartdocResults = await generateDocsBase();
-    if (dartdocResults.packageGraph.localPublicLibraries.isEmpty) {
-      throw DartdocFailure('dartdoc could not find any libraries to document');
-    }
+      var dartdocResults = await generateDocsBase();
+      if (dartdocResults.packageGraph.localPublicLibraries.isEmpty) {
+        throw DartdocFailure(
+            'dartdoc could not find any libraries to document');
+      }
 
-    final errorCount =
-        dartdocResults.packageGraph.packageWarningCounter.errorCount;
-    if (errorCount > 0) {
-      throw DartdocFailure(
-          'dartdoc encountered $errorCount errors while processing.');
+      final errorCount =
+          dartdocResults.packageGraph.packageWarningCounter.errorCount;
+      if (errorCount > 0) {
+        throw DartdocFailure(
+            'dartdoc encountered $errorCount errors while processing.');
+      }
+      logInfo(
+          'Success! Docs generated into ${dartdocResults.outDir.absolute.path}');
+      return dartdocResults;
+    } finally {
+      // Clear out any cached tool snapshots and temporary directories.
+      // ignore: unawaited_futures
+      SnapshotCache.instance.dispose();
+      // ignore: unawaited_futures
+      ToolTempFileTracker.instance.dispose();
     }
-    logInfo(
-        'Success! Docs generated into ${dartdocResults.outDir.absolute.path}');
-    return dartdocResults;
   }
 
   /// Warn on file paths.
@@ -429,6 +460,37 @@ class Dartdoc extends PackageBuilder {
     _doOrphanCheck(packageGraph, origin, visited);
     _doSearchIndexCheck(packageGraph, origin, visited);
   }
+
+  /// Runs [generateDocs] function and properly handles the errors.
+  void executeGuarded() {
+    onCheckProgress.listen(logProgress);
+    // This function should *never* await `runZonedGuarded` because the errors
+    // thrown in generateDocs are uncaught. We want this because uncaught errors
+    // cause IDE debugger to automatically stop at the exception.
+    //
+    // If you await the zone, the code that comes after the await is not
+    // executed if the zone dies due to uncaught error. To avoid this confusion,
+    // never await `runZonedGuarded` and never change the return value of
+    // [executeGuarded].
+    runZonedGuarded(
+      generateDocs,
+      (e, chain) {
+        if (e is DartdocFailure) {
+          stderr.writeln('\ndartdoc failed: ${e}.');
+          if (config.verboseWarnings) {
+            stderr.writeln(chain);
+          }
+          exitCode = 1;
+        } else {
+          stderr.writeln('\ndartdoc failed: ${e}\n${chain}');
+          exitCode = 255;
+        }
+      },
+      zoneSpecification: ZoneSpecification(
+        print: (_, __, ___, String line) => logPrint(line),
+      ),
+    );
+  }
 }
 
 /// This class is returned if dartdoc fails in an expected way (for instance, if