Deprecate some _public_ top-level variables. (#2307)

Deprecate some _public_ top-level variables.

* io_utils.dart: `libraryNameRegexp`, `partOfRegexp`, `newLinePartOfRegexp`
* categorization.dart: `categoryRegexp`
* model_element.dart: `needsPrecacheRegExp`, `htmlInjectRegExp`, `macroRegExp`
* source_linker.dart: `uriTemplateRegexp`

Also, simplify use of RegExp in package_builder.dart.

Also, use spread in tool_runner.dart

Also document public APIs.

Author: srawlins

lib/src/io_utils.dart

@@ -77,11 +77,20 @@ Iterable<String> _doList(
 /// * dart.dartdoc => dart_dartdoc.html
 /// * dart:core => dart_core.html
 String getFileNameFor(String name) =>
-    '${name.replaceAll(libraryNameRegexp, '-')}.html';
+    '${name.replaceAll(_libraryNameRegExp, '-')}.html';
 
-final libraryNameRegexp = RegExp('[.:]');
-final partOfRegexp = RegExp('part of ');
-final newLinePartOfRegexp = RegExp('\npart of ');
+final _libraryNameRegExp = RegExp('[.:]');
+@Deprecated('Public variable intended to be private; will be removed as early '
+    'as Dartdoc 1.0.0')
+RegExp get libraryNameRegexp => _libraryNameRegExp;
+
+@Deprecated('Public variable intended to be private; will be removed as early '
+    'as Dartdoc 1.0.0')
+final RegExp partOfRegexp = RegExp('part of ');
+
+@Deprecated('Public variable intended to be private; will be removed as early '
+    'as Dartdoc 1.0.0')
+final RegExp newLinePartOfRegexp = RegExp('\npart of ');
 
 /// Best used with Future<void>.
 class MultiFutureTracker<T> {

lib/src/model/categorization.dart

@@ -4,10 +4,14 @@
 
 import 'package:dartdoc/src/model/model.dart';
 
-final categoryRegexp = RegExp(
+final RegExp _categoryRegExp = RegExp(
     r'[ ]*{@(api|category|subCategory|image|samples) (.+?)}[ ]*\n?',
     multiLine: true);
 
+@Deprecated('Public variable intended to be private; will be removed as early '
+    'as Dartdoc 1.0.0')
+RegExp get categoryRegexp => _categoryRegExp;
+
 /// Mixin implementing dartdoc categorization for ModelElements.
 abstract class Categorization implements ModelElement {
   @override
@@ -22,7 +26,7 @@ abstract class Categorization implements ModelElement {
     var _subCategorySet = <String>{};
     _hasCategorization = false;
 
-    rawDocs = rawDocs.replaceAllMapped(categoryRegexp, (match) {
+    rawDocs = rawDocs.replaceAllMapped(_categoryRegExp, (match) {
       _hasCategorization = true;
       switch (match[1]) {
         case 'category':

lib/src/model/model_element.dart

@@ -65,11 +65,17 @@ int byFeatureOrdering(String a, String b) {
 
 /// This doc may need to be processed in case it has a template or html
 /// fragment.
-final needsPrecacheRegExp = RegExp(r'{@(template|tool|inject-html)');
+final RegExp needsPrecacheRegExp = RegExp(r'{@(template|tool|inject-html)');
 
-final htmlInjectRegExp = RegExp(r'<dartdoc-html>([a-f0-9]+)</dartdoc-html>');
+final _htmlInjectRegExp = RegExp(r'<dartdoc-html>([a-f0-9]+)</dartdoc-html>');
+@Deprecated('Public variable intended to be private; will be removed as early '
+    'as Dartdoc 1.0.0')
+RegExp get htmlInjectRegExp => _htmlInjectRegExp;
 
-final macroRegExp = RegExp(r'{@macro\s+([^}]+)}');
+final _macroRegExp = RegExp(r'{@macro\s+([^}]+)}');
+@Deprecated('Public variable intended to be private; will be removed as early '
+    'as Dartdoc 1.0.0')
+RegExp get macroRegExp => _macroRegExp;
 
 // TODO(jcollins-g): Implement resolution per ECMA-408 4th edition, page 39 #22.
 /// Resolves this very rare case incorrectly by picking the closest element in
@@ -1198,7 +1204,7 @@ abstract class ModelElement extends Canonicalization
   String _injectHtmlFragments(String rawDocs) {
     if (!config.injectHtml) return rawDocs;
 
-    return rawDocs.replaceAllMapped(htmlInjectRegExp, (match) {
+    return rawDocs.replaceAllMapped(_htmlInjectRegExp, (match) {
       var fragment = packageGraph.getHtmlFragment(match[1]);
       if (fragment == null) {
         warn(PackageWarning.unknownHtmlFragment, message: match[1]);
@@ -1234,7 +1240,7 @@ abstract class ModelElement extends Canonicalization
   ///     More comments
   ///
   String _injectMacros(String rawDocs) {
-    return rawDocs.replaceAllMapped(macroRegExp, (match) {
+    return rawDocs.replaceAllMapped(_macroRegExp, (match) {
       var macro = packageGraph.getMacro(match[1]);
       if (macro == null) {
         warn(PackageWarning.unknownMacro, message: match[1]);

lib/src/model/package_builder.dart

@@ -338,8 +338,8 @@ class PubPackageBuilder implements PackageBuilder {
             // Only add the file if it does not contain 'part of'
             var contents = File(lib).readAsStringSync();
 
-            if (contents.contains(newLinePartOfRegexp) ||
-                contents.startsWith(partOfRegexp)) {
+            if (contents.startsWith('part of ') ||
+                contents.contains('\npart of ')) {
               // NOOP: it's a part file
             } else {
               yield lib;

lib/src/source_linker.dart

@@ -10,7 +10,10 @@ import 'package:dartdoc/src/model/model.dart';
 import 'package:meta/meta.dart';
 import 'package:path/path.dart' as path;
 
-final uriTemplateRegexp = RegExp(r'(%[frl]%)');
+final _uriTemplateRegExp = RegExp(r'(%[frl]%)');
+@Deprecated('Public variable intended to be private; will be removed as early '
+    'as Dartdoc 1.0.0')
+RegExp get uriTemplateRegexp => _uriTemplateRegExp;
 
 abstract class SourceLinkerOptionContext implements DartdocOptionContextBase {
   List<String> get linkToSourceExcludes =>
@@ -105,7 +108,7 @@ class SourceLinker {
             .any((String exclude) => path.isWithin(exclude, sourceFileName))) {
       return '';
     }
-    return uriTemplate.replaceAllMapped(uriTemplateRegexp, (match) {
+    return uriTemplate.replaceAllMapped(_uriTemplateRegExp, (match) {
       switch (match[1]) {
         case '%f%':
           var urlContext = path.Context(style: path.Style.url);

lib/src/tool_runner.dart

@@ -163,8 +163,9 @@ class ToolRunner {
     // or $VAR form.
     var envWithInput = {
       'INPUT': tmpFile.absolute.path,
-      'TOOL_COMMAND': toolDefinition.command[0]
-    }..addAll(environment);
+      'TOOL_COMMAND': toolDefinition.command[0],
+      ...environment,
+    };
     if (toolDefinition is DartToolDefinition) {
       // Put the original command path into the environment, because when it
       // runs as a snapshot, Platform.script (inside the tool script) refers to

lib/src/warnings.dart

@@ -380,7 +380,7 @@ class PackageWarningOptions {
 }
 
 class PackageWarningCounter {
-  final countedWarnings = <Element, Set<Tuple2<PackageWarning, String>>>{};
+  final Map<Element, Set<Tuple2<PackageWarning, String>>> countedWarnings = {};
   final _items = <Jsonable>[];
   final _displayedWarningCounts = <PackageWarning, int>{};
   final PackageGraph packageGraph;