From 160f5f03e0e5a7dc98f7aa2b6db778a10eeffd64 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Thu, 3 Sep 2020 08:47:03 -0700 Subject: [PATCH] Rename some fields which erroneously reference "default" constructors. A "default constructor" is an unnamed, zero-arg constructor. But the constructors being referenced in these fields are just "unnamed." * Deprecated `Class.defaultConstructor`: use `Class.unnamedConstructor`. * Deprecated `Constructor.isDefaultConstructor`: use `Constructor.isUnnamedConstructor`. --- lib/src/markdown_processor.dart | 48 ++++++++++++++++++++------------- lib/src/model/class.dart | 15 +++++++---- lib/src/model/constructor.dart | 9 +++++-- test/end2end/model_test.dart | 2 +- 4 files changed, 47 insertions(+), 27 deletions(-) diff --git a/lib/src/markdown_processor.dart b/lib/src/markdown_processor.dart index 1413c2dcd9..5cfabf5df5 100644 --- a/lib/src/markdown_processor.dart +++ b/lib/src/markdown_processor.dart @@ -345,37 +345,41 @@ class _MarkdownCommentReference { packageGraph = library.packageGraph; } - String __impliedDefaultConstructor; - bool __impliedDefaultConstructorIsSet = false; + String __impliedUnnamedConstructor; - /// Returns the name of the implied default constructor if there is one, or + /// [_impliedUnnamedConstructor] is memoized in [__impliedUnnamedConstructor], + /// but even after it is initialized, it may be null. This bool represents the + /// initializiation state. + bool __impliedUnnamedConstructorIsSet = false; + + /// Returns the name of the implied unnamed constructor if there is one, or /// null if not. /// - /// Default constructors are a special case in dartdoc. If we look up a name + /// Unnamed constructors are a special case in dartdoc. If we look up a name /// within a class of that class itself, the first thing we find is the - /// default constructor. But we determine whether that's what they actually + /// unnamed constructor. But we determine whether that's what they actually /// intended (vs. the enclosing class) by context -- whether they seem /// to be calling it with () or have a 'new' in front of it, or /// whether the name is repeated. /// /// Similarly, referencing a class by itself might actually refer to its - /// constructor based on these same heuristics. + /// unnamed constructor based on these same heuristics. /// - /// With the name of the implied default constructor, other methods can + /// With the name of the implied unnamed constructor, other methods can /// determine whether or not the constructor and/or class we resolved to /// is actually matching the user's intent. - String get _impliedDefaultConstructor { - if (!__impliedDefaultConstructorIsSet) { - __impliedDefaultConstructorIsSet = true; + String get _impliedUnnamedConstructor { + if (!__impliedUnnamedConstructorIsSet) { + __impliedUnnamedConstructorIsSet = true; if (codeRef.contains(_constructorIndicationPattern) || (codeRefChompedParts.length >= 2 && codeRefChompedParts[codeRefChompedParts.length - 1] == codeRefChompedParts[codeRefChompedParts.length - 2])) { // If the last two parts of the code reference are equal, this is probably a default constructor. - __impliedDefaultConstructor = codeRefChompedParts.last; + __impliedUnnamedConstructor = codeRefChompedParts.last; } } - return __impliedDefaultConstructor; + return __impliedUnnamedConstructor; } /// Calculate reference to a ModelElement. @@ -593,18 +597,24 @@ class _MarkdownCommentReference { } } - /// Transform members of [toConvert] that are classes to their default constructor, - /// if a constructor is implied. If not, do the reverse conversion for default - /// constructors. + /// Returns the unnamed constructor for class [toConvert] or the class for + /// constructor [toConvert], or just [toConvert], based on hueristics. + /// + /// * If an unnamed constructor is implied in the comment reference, and + /// [toConvert] is a class with the same name, the class's unnamed + /// constructor is returned. + /// * Otherwise, if [toConvert] is an unnamed constructor, its enclosing + /// class is returned. + /// * Othwerwise, [toConvert] is returned. ModelElement _convertConstructors(ModelElement toConvert) { - if (_impliedDefaultConstructor != null) { - if (toConvert is Class && toConvert.name == _impliedDefaultConstructor) { - return toConvert.defaultConstructor; + if (_impliedUnnamedConstructor != null) { + if (toConvert is Class && toConvert.name == _impliedUnnamedConstructor) { + return toConvert.unnamedConstructor; } return toConvert; } else { if (toConvert is Constructor && - (toConvert.enclosingElement as Class).defaultConstructor == + (toConvert.enclosingElement as Class).unnamedConstructor == toConvert) { return toConvert.enclosingElement; } diff --git a/lib/src/model/class.dart b/lib/src/model/class.dart index b1c068d456..228a2341ab 100644 --- a/lib/src/model/class.dart +++ b/lib/src/model/class.dart @@ -60,14 +60,19 @@ class Class extends Container packageGraph.specialClasses.addSpecial(this); } - Constructor _defaultConstructor; + Constructor _unnamedConstructor; - Constructor get defaultConstructor { - _defaultConstructor ??= constructors - .firstWhere((c) => c.isDefaultConstructor, orElse: () => null); - return _defaultConstructor; + Constructor get unnamedConstructor { + _unnamedConstructor ??= constructors + .firstWhere((c) => c.isUnnamedConstructor, orElse: () => null); + return _unnamedConstructor; } + @Deprecated( + 'Renamed to `unnamedConstructor`; this getter with the old name will be ' + 'removed as early as Dartdoc 1.0.0') + Constructor get defaultConstructor => unnamedConstructor; + @override Iterable get instanceMethods => quiver.concat([super.instanceMethods, inheritedMethods]); diff --git a/lib/src/model/constructor.dart b/lib/src/model/constructor.dart index 2dcb90311d..9494f65ad4 100644 --- a/lib/src/model/constructor.dart +++ b/lib/src/model/constructor.dart @@ -46,7 +46,7 @@ class Constructor extends ModelElement @override String get fullyQualifiedName { - if (isDefaultConstructor) return super.fullyQualifiedName; + if (isUnnamedConstructor) return super.fullyQualifiedName; return '${library.name}.$name'; } @@ -63,7 +63,12 @@ class Constructor extends ModelElement @override bool get isConst => _constructor.isConst; - bool get isDefaultConstructor => name == enclosingElement.name; + bool get isUnnamedConstructor => name == enclosingElement.name; + + @Deprecated( + 'Renamed to `isUnnamedConstructor`; this getter with the old name will ' + 'be removed as early as Dartdoc 1.0.0') + bool get isDefaultConstructor => isUnnamedConstructor; bool get isFactory => _constructor.isFactory; diff --git a/test/end2end/model_test.dart b/test/end2end/model_test.dart index bb7815dcab..64dc127396 100644 --- a/test/end2end/model_test.dart +++ b/test/end2end/model_test.dart @@ -3353,7 +3353,7 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans, .firstWhere((c) => c.name == 'ReferToADefaultConstructor'); withSyntheticConstructor = exLibrary.classes .firstWhere((c) => c.name == 'WithSyntheticConstructor'); - syntheticConstructor = withSyntheticConstructor.defaultConstructor; + syntheticConstructor = withSyntheticConstructor.unnamedConstructor; }); test('calculates comment references to classes vs. constructors correctly',