Allow fine-grained warning control with flags and dartdoc_options.yaml files (#1891)

* basic tests working

* dartfmt

* Rebuild test package docs

* update test package docs

* handle some nulls

* seems to work now even in mixed prefix case

* rebuild stable docs

* dartfmt

* Rebuild test package docs

* Beginnings of some better warning support

* add comment

* Rewritten warnings pass original tests (but no new tests yet)

* Disallow local by default

* fix null element warnings

* add test for warning control

* dartfmt

* Update README

* Remove an unused getter and fix typo in README

Author: jcollins-g

README.md

@@ -102,7 +102,7 @@ authoring doc comments for Dart with `dartdoc`.
 Creating a file named dartdoc_options.yaml at the top of your package can change how Dartdoc
 generates docs.  
 
-An example:
+An example (not necessarily recommended settings):
 
 ```yaml
 dartdoc:
@@ -119,6 +119,12 @@ dartdoc:
   linkTo:
     url: "https://my.dartdocumentationsite.org/dev/%v%"
   showUndocumentedCategories: true
+  ignore:
+    - ambiguous-doc-reference
+  errors:
+    - unresolved-doc-reference
+  warnings:
+    - tool-error
 ```
 
 Unrecognized options will be ignored.  Supported options:
@@ -133,10 +139,14 @@ Unrecognized options will be ignored.  Supported options:
     directives.
   * **exclude**:  Specify a list of library names to avoid generating docs for,
     overriding any specified in include.
+  * **errors**:  Specify warnings to be treated as errors.  See the lists of valid warnings in the command
+    line help for `--errors`, `--warnings`, and `--ignore`.
   * **favicon**:  A path to a favicon for the generated docs.
   * **footer**: A list of paths to footer files containing HTML text.
   * **footerText**: A list of paths to text files for optional text next to the package name and version
   * **header**:  A list of paths to header files containing HTML text.
+  * **ignore**:  Specify warnings to be completely ignored.  See the lists of valid warnings in the command
+    line help for `--errors`, `--warnings`, and `--ignore`.
   * **include**:  Specify a list of library names to generate docs for, ignoring all others.
   * **includeExternal**:  Specify a list of library filenames to add to the list of documented libraries.
   * **linkTo**:  For other packages depending on this one, if this map is defined those packages
@@ -152,6 +162,8 @@ Unrecognized options will be ignored.  Supported options:
         No branch is considered to be "stable".
       * `%n%`: The name of this package, as defined in pubspec.yaml.
       * `%v%`: The version of this package as defined in pubspec.yaml.
+  * **warnings**:  Specify otherwise ignored or set-to-error warnings to simply warn.  See the lists
+    of valid warnings in the command line help for `--errors`, `--warnings`, and `--ignore`.
 
 In general, paths are relative to the directory the dartdoc_options.yaml the option is defined in
 and should be specified as POSIX paths.  Dartdoc will convert POSIX paths automatically on Windows.

lib/dartdoc.dart

@@ -131,7 +131,6 @@ class Dartdoc extends PackageBuilder {
     final int errorCount =
         dartdocResults.packageGraph.packageWarningCounter.errorCount;
     if (errorCount > 0) {
-      dartdocResults.packageGraph.flushWarnings();
       throw new DartdocFailure(
           "dartdoc encountered $errorCount} errors while processing.");
     }

lib/src/dartdoc_options.dart

@@ -24,6 +24,7 @@ import 'package:dartdoc/src/experiment_options.dart';
 import 'package:dartdoc/src/io_utils.dart';
 import 'package:dartdoc/src/tool_runner.dart';
 import 'package:dartdoc/src/tuple.dart';
+import 'package:dartdoc/src/warnings.dart';
 import 'package:path/path.dart' as pathLib;
 import 'package:yaml/yaml.dart';
 
@@ -1271,7 +1272,7 @@ abstract class DartdocOptionContextBase {
 /// a single [ModelElement], [Package], [Category] and so forth has a single context
 /// and so this can be made a member variable of those structures.
 class DartdocOptionContext extends DartdocOptionContextBase
-    with DartdocExperimentOptionContext {
+    with DartdocExperimentOptionContext, PackageWarningOptionContext {
   @override
   final DartdocOptionSet optionSet;
   @override
@@ -1357,12 +1358,10 @@ class DartdocOptionContext extends DartdocOptionContextBase
   String get sdkDir => optionSet['sdkDir'].valueAt(context);
   bool get showUndocumentedCategories =>
       optionSet['showUndocumentedCategories'].valueAt(context);
-  bool get showWarnings => optionSet['showWarnings'].valueAt(context);
   PackageMeta get topLevelPackageMeta =>
       optionSet['topLevelPackageMeta'].valueAt(context);
   bool get useCategories => optionSet['useCategories'].valueAt(context);
   bool get validateLinks => optionSet['validateLinks'].valueAt(context);
-  bool get verboseWarnings => optionSet['verboseWarnings'].valueAt(context);
 
   bool isLibraryExcluded(String name) =>
       exclude.any((pattern) => name == pattern);
@@ -1540,8 +1539,6 @@ Future<List<DartdocOption>> createDartdocOptions() async {
     }, help: 'Path to the SDK directory.', isDir: true, mustExist: true),
     new DartdocOptionArgFile<bool>('showUndocumentedCategories', false,
         help: "Label categories that aren't documented", negatable: true),
-    new DartdocOptionArgOnly<bool>('showWarnings', false,
-        help: 'Display all warnings.'),
     new DartdocOptionSyntheticOnly<PackageMeta>('topLevelPackageMeta',
         (DartdocSyntheticOption<PackageMeta> option, Directory dir) {
       PackageMeta packageMeta = new PackageMeta.fromDir(
@@ -1574,5 +1571,7 @@ Future<List<DartdocOption>> createDartdocOptions() async {
             'command.'),
     // TODO(jcollins-g): refactor so there is a single static "create" for
     // each DartdocOptionContext that traverses the inheritance tree itself.
-  ]..addAll(await createExperimentOptions());
+  ]
+    ..addAll(await createExperimentOptions())
+    ..addAll(await createPackageWarningOptions());
 }

lib/src/model.dart

@@ -3632,6 +3632,7 @@ abstract class ModelElement extends Canonicalization
   @override
   PackageGraph get packageGraph => _packageGraph;
 
+  @override
   Package get package => library.package;
 
   bool get isPublicAndPackageDocumented =>
@@ -4621,15 +4622,10 @@ class Operator extends Method {
 
 class PackageGraph {
   PackageGraph.UninitializedPackageGraph(
-      this.config,
-      PackageWarningOptions packageWarningOptions,
-      this.driver,
-      this.sdk,
-      this.hasEmbedderSdk)
+      this.config, this.driver, this.sdk, this.hasEmbedderSdk)
       : packageMeta = config.topLevelPackageMeta,
-        session = driver.currentSession,
-        _packageWarningCounter =
-            new PackageWarningCounter(packageWarningOptions) {
+        session = driver.currentSession {
+    _packageWarningCounter = new PackageWarningCounter(this);
     // Make sure the default package exists, even if it has no libraries.
     // This can happen for packages that only contain embedder SDKs.
     new Package.fromPackageMeta(packageMeta, this);
@@ -4815,14 +4811,6 @@ class PackageGraph {
     return (_allRootDirs.contains(element.library.packageMeta?.resolvedDir));
   }
 
-  /// Flush out any warnings we might have collected while
-  /// [PackageWarningOptions.autoFlush] was false.
-  void flushWarnings() {
-    _packageWarningCounter.maybeFlush();
-  }
-
-  Tuple2<int, int> get lineAndColumn => null;
-
   PackageWarningCounter get packageWarningCounter => _packageWarningCounter;
 
   final Set<Tuple3<Element, PackageWarning, String>> _warnAlreadySeen =
@@ -4871,6 +4859,7 @@ class PackageGraph {
       return;
     }
     // Some kinds of warnings it is OK to drop if we're not documenting them.
+    // TODO(jcollins-g): drop this and use new flag system instead.
     if (warnable != null &&
         skipWarningIfNotDocumentedFor.contains(kind) &&
         !warnable.isDocumented) {
@@ -5610,6 +5599,7 @@ class Category extends Nameable
         Indexable
     implements Documentable {
   /// All libraries in [libraries] must come from [package].
+  @override
   Package package;
   String _name;
   @override
@@ -5965,6 +5955,9 @@ class Package extends LibraryContainer
   @override
   String get name => _name;
 
+  @override
+  Package get package => this;
+
   @override
   PackageGraph get packageGraph => _packageGraph;
 
@@ -6360,7 +6353,7 @@ class PackageBuilder {
     }
 
     PackageGraph newGraph = new PackageGraph.UninitializedPackageGraph(
-        config, getWarningOptions(), driver, sdk, hasEmbedderSdkFiles);
+        config, driver, sdk, hasEmbedderSdkFiles);
     await getLibraries(newGraph);
     await newGraph.initializePackageGraph();
     return newGraph;
@@ -6480,25 +6473,6 @@ class PackageBuilder {
     return _driver;
   }
 
-  PackageWarningOptions getWarningOptions() {
-    PackageWarningOptions warningOptions =
-        new PackageWarningOptions(config.verboseWarnings);
-    // TODO(jcollins-g): explode this into detailed command line options.
-    for (PackageWarning kind in PackageWarning.values) {
-      switch (kind) {
-        case PackageWarning.toolError:
-        case PackageWarning.invalidParameter:
-        case PackageWarning.unresolvedExport:
-          warningOptions.error(kind);
-          break;
-        default:
-          if (config.showWarnings) warningOptions.warn(kind);
-          break;
-      }
-    }
-    return warningOptions;
-  }
-
   /// Return an Iterable with the sdk files we should parse.
   /// Filter can be String or RegExp (technically, anything valid for
   /// [String.contains])