From 52689766ea1445c5bee132cf9501fd7d80c62ce4 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Mon, 17 Aug 2020 16:19:52 -0700 Subject: [PATCH 1/2] 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. --- lib/src/io_utils.dart | 12 ++++++++---- lib/src/model/categorization.dart | 8 ++++++-- lib/src/model/model_element.dart | 16 +++++++++++----- lib/src/model/package_builder.dart | 4 ++-- lib/src/source_linker.dart | 7 +++++-- lib/src/tool_runner.dart | 5 +++-- lib/src/warnings.dart | 2 +- 7 files changed, 36 insertions(+), 18 deletions(-) diff --git a/lib/src/io_utils.dart b/lib/src/io_utils.dart index 7709a3641a..09fb9ff3e8 100644 --- a/lib/src/io_utils.dart +++ b/lib/src/io_utils.dart @@ -77,11 +77,15 @@ Iterable _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; + +final RegExp partOfRegexp = RegExp('part of '); +final RegExp newLinePartOfRegexp = RegExp('\npart of '); /// Best used with Future. class MultiFutureTracker { diff --git a/lib/src/model/categorization.dart b/lib/src/model/categorization.dart index 5202a03e30..06acc6bb70 100644 --- a/lib/src/model/categorization.dart +++ b/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 = {}; _hasCategorization = false; - rawDocs = rawDocs.replaceAllMapped(categoryRegexp, (match) { + rawDocs = rawDocs.replaceAllMapped(_categoryRegexp, (match) { _hasCategorization = true; switch (match[1]) { case 'category': diff --git a/lib/src/model/model_element.dart b/lib/src/model/model_element.dart index 87f4f29687..0fc0edcfc9 100644 --- a/lib/src/model/model_element.dart +++ b/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'([a-f0-9]+)'); +final _htmlInjectRegExp = RegExp(r'([a-f0-9]+)'); +@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]); diff --git a/lib/src/model/package_builder.dart b/lib/src/model/package_builder.dart index 44ecb5919c..8d90216a79 100644 --- a/lib/src/model/package_builder.dart +++ b/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; diff --git a/lib/src/source_linker.dart b/lib/src/source_linker.dart index 10cd0bfce4..e305728686 100644 --- a/lib/src/source_linker.dart +++ b/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 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); diff --git a/lib/src/tool_runner.dart b/lib/src/tool_runner.dart index 7071a8e56e..b8f7d5374f 100644 --- a/lib/src/tool_runner.dart +++ b/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 diff --git a/lib/src/warnings.dart b/lib/src/warnings.dart index c56afef3b5..6f60b5677f 100644 --- a/lib/src/warnings.dart +++ b/lib/src/warnings.dart @@ -380,7 +380,7 @@ class PackageWarningOptions { } class PackageWarningCounter { - final countedWarnings = >>{}; + final Map>> countedWarnings = {}; final _items = []; final _displayedWarningCounts = {}; final PackageGraph packageGraph; From 4accc730ba7a2ef9239fc2d5caf3f24cf00bc58b Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Mon, 17 Aug 2020 16:29:43 -0700 Subject: [PATCH 2/2] Nits --- lib/src/io_utils.dart | 11 ++++++++--- lib/src/model/categorization.dart | 6 +++--- lib/src/source_linker.dart | 6 +++--- 3 files changed, 14 insertions(+), 9 deletions(-) diff --git a/lib/src/io_utils.dart b/lib/src/io_utils.dart index 09fb9ff3e8..33a8c6117e 100644 --- a/lib/src/io_utils.dart +++ b/lib/src/io_utils.dart @@ -77,14 +77,19 @@ Iterable _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 _libraryNameRegExp = RegExp('[.:]'); @Deprecated('Public variable intended to be private; will be removed as early ' 'as Dartdoc 1.0.0') -RegExp get libraryNameRegexp => _libraryNameRegexp; +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. diff --git a/lib/src/model/categorization.dart b/lib/src/model/categorization.dart index 06acc6bb70..afed68b8ce 100644 --- a/lib/src/model/categorization.dart +++ b/lib/src/model/categorization.dart @@ -4,13 +4,13 @@ import 'package:dartdoc/src/model/model.dart'; -final RegExp _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; +RegExp get categoryRegexp => _categoryRegExp; /// Mixin implementing dartdoc categorization for ModelElements. abstract class Categorization implements ModelElement { @@ -26,7 +26,7 @@ abstract class Categorization implements ModelElement { var _subCategorySet = {}; _hasCategorization = false; - rawDocs = rawDocs.replaceAllMapped(_categoryRegexp, (match) { + rawDocs = rawDocs.replaceAllMapped(_categoryRegExp, (match) { _hasCategorization = true; switch (match[1]) { case 'category': diff --git a/lib/src/source_linker.dart b/lib/src/source_linker.dart index e305728686..f4dafdbf9a 100644 --- a/lib/src/source_linker.dart +++ b/lib/src/source_linker.dart @@ -10,10 +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; +RegExp get uriTemplateRegexp => _uriTemplateRegExp; abstract class SourceLinkerOptionContext implements DartdocOptionContextBase { List get linkToSourceExcludes => @@ -108,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);