Skip to content

Commit 6c3242a

Browse files
authored
Privatize some of the interface of Library (#2293)
* Change `Library.fromLibraryResult` to be a factory constructor. * Change `Library. _exportedAndLocalElements` from a `List<Element>` to a final `Set<Element>`. * Deprecate the public methods `Library.getDefinedElements`, `Library.getLibraryName`, and getter `Library.allOriginalModelElementNames`. * Adjust doc comments to have a short one-liner. * Extract a RegExp to be static final. * Mark memoized fields as `/*late final*/`.
1 parent 4410c77 commit 6c3242a

File tree

2 files changed

+82
-61
lines changed

2 files changed

+82
-61
lines changed

lib/src/model/library.dart

Lines changed: 76 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -52,19 +52,23 @@ class _HashableChildLibraryElementVisitor
5252
}
5353

5454
class Library extends ModelElement with Categorization, TopLevelContainer {
55-
List<TopLevelVariable> _variables;
56-
List<Element> _exportedAndLocalElements;
57-
String _name;
55+
final Set<Element> _exportedAndLocalElements;
5856
final String _restoredUri;
5957

58+
@override
59+
final Package package;
60+
6061
factory Library(LibraryElement element, PackageGraph packageGraph) {
6162
return packageGraph.findButDoNotCreateLibraryFor(element);
6263
}
6364

64-
Library.fromLibraryResult(DartDocResolvedLibrary resolvedLibrary,
65-
PackageGraph packageGraph, this._package)
66-
: _restoredUri = resolvedLibrary.restoredUri,
67-
super(resolvedLibrary.result.element, null, packageGraph, null) {
65+
Library._(LibraryElement element, PackageGraph packageGraph, this.package,
66+
this._restoredUri, this._exportedAndLocalElements)
67+
: super(element, null, packageGraph, null);
68+
69+
factory Library.fromLibraryResult(DartDocResolvedLibrary resolvedLibrary,
70+
PackageGraph packageGraph, Package package) {
71+
var element = resolvedLibrary.result.element;
6872
if (element == null) throw ArgumentError.notNull('element');
6973

7074
// Initialize [packageGraph]'s cache of ModelNodes for relevant
@@ -76,22 +80,22 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
7680
packageGraph.populateModelNodeFor(e, _compilationUnitMap))
7781
.visitElement(element);
7882

79-
// Initialize the list of elements defined in this library and
80-
// exported via its export directives.
81-
var exportedAndLocalElements =
82-
element.exportNamespace.definedNames.values.toSet();
83-
// TODO(jcollins-g): Consider switch to [_libraryElement.topLevelElements].
84-
exportedAndLocalElements
85-
.addAll(getDefinedElements(element.definingCompilationUnit));
86-
for (var cu in element.parts) {
87-
exportedAndLocalElements.addAll(getDefinedElements(cu));
88-
}
89-
_exportedAndLocalElements = exportedAndLocalElements.toList();
83+
var exportedAndLocalElements = {
84+
// Initialize the list of elements defined in this library and
85+
// exported via its export directives.
86+
...element.exportNamespace.definedNames.values,
87+
// TODO(jcollins-g): Consider switch to [_libraryElement.topLevelElements].
88+
..._getDefinedElements(element.definingCompilationUnit),
89+
for (var cu in element.parts) ..._getDefinedElements(cu),
90+
};
91+
var library = Library._(element, packageGraph, package,
92+
resolvedLibrary.restoredUri, exportedAndLocalElements);
9093

91-
_package.allLibraries.add(this);
94+
package.allLibraries.add(library);
95+
return library;
9296
}
9397

94-
static Iterable<Element> getDefinedElements(
98+
static Iterable<Element> _getDefinedElements(
9599
CompilationUnitElement compilationUnit) {
96100
return quiver.concat([
97101
compilationUnit.accessors,
@@ -105,7 +109,14 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
105109
]);
106110
}
107111

108-
List<String> _allOriginalModelElementNames;
112+
@Deprecated(
113+
'Public method intended to be private; will be removed as early as '
114+
'Dartdoc 1.0.0')
115+
static Iterable<Element> getDefinedElements(
116+
CompilationUnitElement compilationUnit) =>
117+
_getDefinedElements(compilationUnit);
118+
119+
List<String> __allOriginalModelElementNames;
109120

110121
/// Return true if this library is in a package configured to be treated as
111122
/// as using Null safety and itself uses Null safety.
@@ -119,24 +130,14 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
119130

120131
bool get isInSdk => element.isInSdk;
121132

122-
final Package _package;
123-
124-
@override
125-
Package get package {
126-
// Everything must be in a package. TODO(jcollins-g): Support other things
127-
// that look like packages.
128-
assert(_package != null);
129-
return _package;
130-
}
131-
132133
/// [allModelElements] resolved to their original names.
133134
///
134135
/// A collection of [ModelElement.fullyQualifiedName]s for [ModelElement]s
135136
/// documented with this library, but these ModelElements and names correspond
136137
/// to the defining library where each originally came from with respect
137138
/// to inheritance and reexporting. Most useful for error reporting.
138-
Iterable<String> get allOriginalModelElementNames {
139-
_allOriginalModelElementNames ??= allModelElements.map((e) {
139+
Iterable<String> get _allOriginalModelElementNames {
140+
__allOriginalModelElementNames ??= allModelElements.map((e) {
140141
if (e is GetterSetterCombo) {
141142
Accessor getter;
142143
Accessor setter;
@@ -160,9 +161,15 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
160161
packageGraph)
161162
.fullyQualifiedName;
162163
}).toList();
163-
return _allOriginalModelElementNames;
164+
return __allOriginalModelElementNames;
164165
}
165166

167+
@Deprecated(
168+
'Public getter intended to be private; will be removed as early as '
169+
'Dartdoc 1.0.0')
170+
Iterable<String> get allOriginalModelElementNames =>
171+
_allOriginalModelElementNames;
172+
166173
@override
167174
CharacterLocation get characterLocation {
168175
if (element.nameOffset == -1) {
@@ -183,7 +190,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
183190
@override
184191
LibraryElement get element => super.element;
185192

186-
List<Extension> _extensions;
193+
/*late final*/ List<Extension> _extensions;
187194

188195
@override
189196
Iterable<Extension> get extensions {
@@ -215,7 +222,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
215222
return true;
216223
}
217224

218-
List<TopLevelVariable> _constants;
225+
/*late final*/ List<TopLevelVariable> _constants;
219226

220227
@override
221228
Iterable<TopLevelVariable> get constants {
@@ -224,7 +231,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
224231
return _constants;
225232
}
226233

227-
Set<Library> _packageImportedExportedLibraries;
234+
/*late final*/ Set<Library> _packageImportedExportedLibraries;
228235

229236
/// Returns all libraries either imported by or exported by any public library
230237
/// this library's package. (Not [PackageGraph], but sharing a package name).
@@ -245,7 +252,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
245252
return _packageImportedExportedLibraries;
246253
}
247254

248-
Set<Library> _importedExportedLibraries;
255+
/*late final*/ Set<Library> _importedExportedLibraries;
249256

250257
/// Returns all libraries either imported by or exported by this library,
251258
/// recursively.
@@ -264,7 +271,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
264271
return _importedExportedLibraries;
265272
}
266273

267-
Map<String, Set<Library>> _prefixToLibrary;
274+
/*late final*/ Map<String, Set<Library>> _prefixToLibrary;
268275

269276
/// Map of import prefixes ('import "foo" as prefix;') to [Library].
270277
Map<String, Set<Library>> get prefixToLibrary {
@@ -283,7 +290,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
283290
return _prefixToLibrary;
284291
}
285292

286-
String _dirName;
293+
/*late final*/ String _dirName;
287294

288295
String get dirName {
289296
if (_dirName == null) {
@@ -296,7 +303,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
296303
return _dirName;
297304
}
298305

299-
Set<String> _canonicalFor;
306+
/*late final*/ Set<String> _canonicalFor;
300307

301308
Set<String> get canonicalFor {
302309
if (_canonicalFor == null) {
@@ -306,6 +313,8 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
306313
return _canonicalFor;
307314
}
308315

316+
static final _canonicalRegExp = RegExp(r'{@canonicalFor\s([^}]+)}');
317+
309318
/// Hide canonicalFor from doc while leaving a note to ourselves to
310319
/// help with ambiguous canonicalization determination.
311320
///
@@ -316,14 +325,13 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
316325
rawDocs = super.buildDocumentationAddition(rawDocs);
317326
var newCanonicalFor = <String>{};
318327
var notFoundInAllModelElements = <String>{};
319-
final canonicalRegExp = RegExp(r'{@canonicalFor\s([^}]+)}');
320-
rawDocs = rawDocs.replaceAllMapped(canonicalRegExp, (Match match) {
328+
rawDocs = rawDocs.replaceAllMapped(_canonicalRegExp, (Match match) {
321329
newCanonicalFor.add(match.group(1));
322330
notFoundInAllModelElements.add(match.group(1));
323331
return '';
324332
});
325333
if (notFoundInAllModelElements.isNotEmpty) {
326-
notFoundInAllModelElements.removeAll(allOriginalModelElementNames);
334+
notFoundInAllModelElements.removeAll(_allOriginalModelElementNames);
327335
}
328336
for (var notFound in notFoundInAllModelElements) {
329337
warn(PackageWarning.ignoredCanonicalFor, message: notFound);
@@ -338,7 +346,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
338346
@override
339347
ModelElement get enclosingElement => null;
340348

341-
List<Enum> _enums;
349+
/*late final*/ List<Enum> _enums;
342350

343351
@override
344352
List<Enum> get enums {
@@ -351,7 +359,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
351359
return _enums;
352360
}
353361

354-
List<Mixin> _mixins;
362+
/*late final*/ List<Mixin> _mixins;
355363

356364
@override
357365
List<Mixin> get mixins {
@@ -364,7 +372,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
364372
return _mixins;
365373
}
366374

367-
List<Class> _exceptions;
375+
/*late final*/ List<Class> _exceptions;
368376

369377
@override
370378
List<Class> get exceptions {
@@ -401,6 +409,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
401409

402410
InheritanceManager3 _inheritanceManager;
403411

412+
// TODO(srawlins): Make a static field, likely on [Class].
404413
InheritanceManager3 get inheritanceManager {
405414
_inheritanceManager ??= InheritanceManager3();
406415
return _inheritanceManager;
@@ -414,13 +423,15 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
414423
@override
415424
Library get library => this;
416425

426+
/*late final*/ String _name;
427+
417428
@override
418429
String get name {
419-
_name ??= getLibraryName(element);
430+
_name ??= _getLibraryName(element);
420431
return _name;
421432
}
422433

423-
String _nameFromPath;
434+
/*late final*/ String _nameFromPath;
424435

425436
/// Generate a name for this library based on its location.
426437
///
@@ -448,7 +459,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
448459
return _packageMeta;
449460
}
450461

451-
List<TopLevelVariable> _properties;
462+
/*late final*/ List<TopLevelVariable> _properties;
452463

453464
/// All variables ("properties") except constants.
454465
@override
@@ -458,7 +469,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
458469
return _properties;
459470
}
460471

461-
List<Typedef> _typedefs;
472+
/*late final*/ List<Typedef> _typedefs;
462473

463474
@override
464475
List<Typedef> get typedefs {
@@ -488,6 +499,8 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
488499
return allClasses.firstWhere((it) => it.name == name, orElse: () => null);
489500
}
490501

502+
/*late final*/ List<TopLevelVariable> _variables;
503+
491504
List<TopLevelVariable> _getVariables() {
492505
if (_variables == null) {
493506
var elements = _exportedAndLocalElements
@@ -517,6 +530,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
517530
}
518531

519532
/// Reverses URIs if needed to get a package URI.
533+
///
520534
/// Not the same as [PackageGraph.name] because there we always strip all
521535
/// path components; this function only strips the package prefix if the
522536
/// library is part of the default package or if it is being documented
@@ -544,7 +558,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
544558
return name;
545559
}
546560

547-
static String getLibraryName(LibraryElement element) {
561+
static String _getLibraryName(LibraryElement element) {
548562
var source = element.source;
549563

550564
if (source.uri.isScheme('dart')) {
@@ -563,7 +577,13 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
563577
return name;
564578
}
565579

566-
Map<String, Set<ModelElement>> _modelElementsNameMap;
580+
@Deprecated(
581+
'Public method intended to be private; will be removed as early as '
582+
'Dartdoc 1.0.0')
583+
static String getLibraryName(LibraryElement element) =>
584+
_getLibraryName(element);
585+
586+
/*late final*/ Map<String, Set<ModelElement>> _modelElementsNameMap;
567587

568588
/// Map of [fullyQualifiedNameWithoutLibrary] to all matching [ModelElement]s
569589
/// in this library. Used for code reference lookups.
@@ -583,7 +603,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
583603
return _modelElementsNameMap;
584604
}
585605

586-
Map<Element, Set<ModelElement>> _modelElementsMap;
606+
/*late final*/ Map<Element, Set<ModelElement>> _modelElementsMap;
587607

588608
Map<Element, Set<ModelElement>> get modelElementsMap {
589609
if (_modelElementsMap == null) {
@@ -628,15 +648,15 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
628648
return _modelElementsMap;
629649
}
630650

631-
List<ModelElement> _allModelElements;
651+
/*late final*/ List<ModelElement> _allModelElements;
632652

633653
Iterable<ModelElement> get allModelElements {
634654
return _allModelElements ??= [
635655
for (var modelElements in modelElementsMap.values) ...modelElements,
636656
];
637657
}
638658

639-
List<ModelElement> _allCanonicalModelElements;
659+
/*late final*/ List<ModelElement> _allCanonicalModelElements;
640660

641661
Iterable<ModelElement> get allCanonicalModelElements {
642662
return (_allCanonicalModelElements ??=

lib/src/model/library_container.dart

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import 'package:dartdoc/src/model/model.dart';
77
import 'package:dartdoc/src/model_utils.dart' as model_utils;
88

99
/// A set of libraries, initialized after construction by accessing [libraries].
10+
///
1011
/// Do not cache return values of any methods or members excepting [libraries]
1112
/// and [name] before finishing initialization of a [LibraryContainer].
1213
abstract class LibraryContainer
@@ -35,11 +36,11 @@ abstract class LibraryContainer
3536
bool get isSdk => false;
3637

3738
/// Returns:
38-
/// -1 if this container is listed in [containerOrder].
39-
/// 0 if this container is named the same as the [enclosingName].
40-
/// 1 if this container represents the SDK.
41-
/// 2 if this group has a name that contains the name [enclosingName].
42-
/// 3 otherwise.
39+
/// * -1 if this container is listed in [containerOrder].
40+
/// * 0 if this container is named the same as the [enclosingName].
41+
/// * 1 if this container represents the SDK.
42+
/// * 2 if this group has a name that contains the name [enclosingName].
43+
/// * 3 otherwise.
4344
int get _group {
4445
if (containerOrder.contains(sortKey)) return -1;
4546
if (equalsIgnoreAsciiCase(sortKey, enclosingName)) return 0;

0 commit comments

Comments
 (0)