[cfe] Update documentation for *References objects
Change-Id: Ib74446de255dc5572783a8945025d9e55881f704
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/435800
Commit-Queue: Johnni Winther <johnniwinther@google.com>
Reviewed-by: Chloe Stefantsova <cstefantsova@google.com>
diff --git a/pkg/front_end/lib/src/fragment/enum_element.dart b/pkg/front_end/lib/src/fragment/enum_element.dart
index 00f169c..f20411b 100644
--- a/pkg/front_end/lib/src/fragment/enum_element.dart
+++ b/pkg/front_end/lib/src/fragment/enum_element.dart
@@ -258,7 +258,7 @@
// Coverage-ignore(suite): Not run.
Iterable<Reference> getExportedGetterReferences(
PropertyReferences references) {
- return [references.getterReference!];
+ return [references.getterReference];
}
@override
diff --git a/pkg/front_end/lib/src/fragment/field/declaration.dart b/pkg/front_end/lib/src/fragment/field/declaration.dart
index b631cd0..3310584 100644
--- a/pkg/front_end/lib/src/fragment/field/declaration.dart
+++ b/pkg/front_end/lib/src/fragment/field/declaration.dart
@@ -693,13 +693,13 @@
@override
Iterable<Reference> getExportedGetterReferences(
PropertyReferences references) {
- return [references.getterReference!];
+ return [references.getterReference];
}
@override
Iterable<Reference> getExportedSetterReferences(
PropertyReferences references) {
- return hasSetter ? [references.setterReference!] : const [];
+ return hasSetter ? [references.setterReference] : const [];
}
}
diff --git a/pkg/front_end/lib/src/fragment/getter/declaration.dart b/pkg/front_end/lib/src/fragment/getter/declaration.dart
index 26757ac..ff956a0 100644
--- a/pkg/front_end/lib/src/fragment/getter/declaration.dart
+++ b/pkg/front_end/lib/src/fragment/getter/declaration.dart
@@ -253,7 +253,7 @@
@override
Iterable<Reference> getExportedGetterReferences(
PropertyReferences references) =>
- [references.getterReference!];
+ [references.getterReference];
@override
VariableDeclaration getFormalParameter(int index) {
diff --git a/pkg/front_end/lib/src/fragment/primary_constructor_field.dart b/pkg/front_end/lib/src/fragment/primary_constructor_field.dart
index 79ec1ca..115a170 100644
--- a/pkg/front_end/lib/src/fragment/primary_constructor_field.dart
+++ b/pkg/front_end/lib/src/fragment/primary_constructor_field.dart
@@ -340,7 +340,7 @@
// Coverage-ignore(suite): Not run.
Iterable<Reference> getExportedGetterReferences(
PropertyReferences references) {
- return [references.getterReference!];
+ return [references.getterReference];
}
@override
diff --git a/pkg/front_end/lib/src/fragment/setter/declaration.dart b/pkg/front_end/lib/src/fragment/setter/declaration.dart
index b925523..05ec363 100644
--- a/pkg/front_end/lib/src/fragment/setter/declaration.dart
+++ b/pkg/front_end/lib/src/fragment/setter/declaration.dart
@@ -255,7 +255,7 @@
@override
Iterable<Reference> getExportedSetterReferences(
PropertyReferences references) =>
- [references.setterReference!];
+ [references.setterReference];
@override
VariableDeclaration getFormalParameter(int index) {
diff --git a/pkg/front_end/lib/src/source/source_constructor_builder.dart b/pkg/front_end/lib/src/source/source_constructor_builder.dart
index 677c0bb..23ca2d4 100644
--- a/pkg/front_end/lib/src/source/source_constructor_builder.dart
+++ b/pkg/front_end/lib/src/source/source_constructor_builder.dart
@@ -593,16 +593,36 @@
}
}
+/// [Reference]s used for the [Member] nodes created for a generative
+/// constructor.
class ConstructorReferences {
Reference? _constructorReference;
Reference? _tearOffReference;
- final bool _hasTearOff;
+ /// If `true`, the generative constructor has a tear-off lowering and should
+ /// therefore have distinct [constructorReference] and [tearOffReference]
+ /// values.
+ final bool _hasTearOffLowering;
+
+ /// Creates a [ConstructorReferences] object preloaded with the
+ /// [preExistingConstructorReference] and [preExistingTearOffReference].
+ ///
+ /// For initial/one-off compilations these are `null`, but for subsequent
+ /// compilations during an incremental compilation, these are the references
+ /// used for the same generative constructor and tear-off in the previous
+ /// compilation.
ConstructorReferences._(
- this._constructorReference, this._tearOffReference, this._hasTearOff)
- : assert(!(_tearOffReference != null && !_hasTearOff),
- "Unexpected tear off reference $_tearOffReference.");
+ {required Reference? preExistingConstructorReference,
+ required Reference? preExistingTearOffReference,
+ required bool hasTearOffLowering})
+ : _constructorReference = preExistingConstructorReference,
+ _tearOffReference = preExistingTearOffReference,
+ _hasTearOffLowering = hasTearOffLowering,
+ assert(!(preExistingTearOffReference != null && !hasTearOffLowering),
+ "Unexpected tear off reference $preExistingTearOffReference.");
+ /// Creates a [ConstructorReferences] object preloaded with the pre-existing
+ /// references from [indexedContainer], if available.
factory ConstructorReferences({
required String name,
required NameScheme nameScheme,
@@ -610,7 +630,7 @@
required SourceLoader loader,
required DeclarationBuilder declarationBuilder,
}) {
- bool hasTearOff = switch (declarationBuilder) {
+ bool hasTearOffLowering = switch (declarationBuilder) {
ClassBuilder() =>
!(declarationBuilder.isAbstract || declarationBuilder.isEnum) &&
loader.target.backendTarget.isConstructorTearOffLoweringEnabled,
@@ -618,20 +638,28 @@
ExtensionTypeDeclarationBuilder() => true,
};
- Reference? constructorReference;
- Reference? tearOffReference;
+ Reference? preExistingConstructorReference;
+ Reference? preExistingTearOffReference;
if (indexedContainer != null) {
- constructorReference = indexedContainer.lookupConstructorReference(
- nameScheme.getConstructorMemberName(name, isTearOff: false).name);
- tearOffReference = indexedContainer.lookupGetterReference(
+ preExistingConstructorReference =
+ indexedContainer.lookupConstructorReference(
+ nameScheme.getConstructorMemberName(name, isTearOff: false).name);
+ preExistingTearOffReference = indexedContainer.lookupGetterReference(
nameScheme.getConstructorMemberName(name, isTearOff: true).name);
}
return new ConstructorReferences._(
- constructorReference, tearOffReference, hasTearOff);
+ preExistingConstructorReference: preExistingConstructorReference,
+ preExistingTearOffReference: preExistingTearOffReference,
+ hasTearOffLowering: hasTearOffLowering);
}
+ /// Registers that [builder] is created for the pre-existing references
+ /// provided in [ConstructorReferences._].
+ ///
+ /// This must be called before [constructorReference] and [tearOffReference]
+ /// are accessed.
void registerReference(
SourceLoader loader, SourceConstructorBuilder builder) {
if (_constructorReference != null) {
@@ -642,9 +670,17 @@
}
}
+ /// The [Reference] used to refer to the [Member] node created for the
+ /// generative constructor.
Reference get constructorReference =>
_constructorReference ??= new Reference();
+ /// The [Reference] used to refer to the [Member] node created for the
+ /// tear-off of the generative constructor.
+ ///
+ /// If a tear-off lowering is created for the generative constructor, this is
+ /// distinct from [constructorReference], otherwise it is the same [Reference]
+ /// as [constructorReference].
Reference get tearOffReference => _tearOffReference ??=
- _hasTearOff ? new Reference() : constructorReference;
+ _hasTearOffLowering ? new Reference() : constructorReference;
}
diff --git a/pkg/front_end/lib/src/source/source_enum_builder.dart b/pkg/front_end/lib/src/source/source_enum_builder.dart
index c3a9fe1..8a42e67 100644
--- a/pkg/front_end/lib/src/source/source_enum_builder.dart
+++ b/pkg/front_end/lib/src/source/source_enum_builder.dart
@@ -861,7 +861,7 @@
// Coverage-ignore(suite): Not run.
Iterable<Reference> getExportedGetterReferences(
PropertyReferences references) {
- return [references.getterReference!];
+ return [references.getterReference];
}
}
diff --git a/pkg/front_end/lib/src/source/source_factory_builder.dart b/pkg/front_end/lib/src/source/source_factory_builder.dart
index bd61fda..ccf5842 100644
--- a/pkg/front_end/lib/src/source/source_factory_builder.dart
+++ b/pkg/front_end/lib/src/source/source_factory_builder.dart
@@ -342,16 +342,35 @@
}
}
+/// [Reference]s used for the [Member] nodes created for a factory constructor.
class FactoryReferences {
Reference? _factoryReference;
Reference? _tearOffReference;
- final bool _hasTearOff;
+ /// If `true`, the factory constructor has a tear-off lowering and should
+ /// therefore have distinct [factoryReference] and [tearOffReference]
+ /// values.
+ final bool _hasTearOffLowering;
+
+ /// Creates a [FactoryReferences] object preloaded with the
+ /// [preExistingFactoryReference] and [preExistingTearOffReference].
+ ///
+ /// For initial/one-off compilations these are `null`, but for subsequent
+ /// compilations during an incremental compilation, these are the references
+ /// used for the same factory constructor and tear-off in the previous
+ /// compilation.
FactoryReferences._(
- this._factoryReference, this._tearOffReference, this._hasTearOff)
- : assert(!(_tearOffReference != null && !_hasTearOff),
- "Unexpected tear off reference $_tearOffReference.");
+ {required Reference? preExistingFactoryReference,
+ required Reference? preExistingTearOffReference,
+ required bool hasTearOffLowering})
+ : _factoryReference = preExistingFactoryReference,
+ _tearOffReference = preExistingTearOffReference,
+ _hasTearOffLowering = hasTearOffLowering,
+ assert(!(preExistingTearOffReference != null && !hasTearOffLowering),
+ "Unexpected tear off reference $preExistingTearOffReference.");
+ /// Creates a [FactoryReferences] object preloaded with the pre-existing
+ /// references from [indexedContainer], if available.
factory FactoryReferences({
required String name,
required NameScheme nameScheme,
@@ -359,27 +378,34 @@
required SourceLoader loader,
required DeclarationBuilder declarationBuilder,
}) {
- bool hasTearOff = switch (declarationBuilder) {
+ bool hasTearOffLowering = switch (declarationBuilder) {
ClassBuilder() =>
loader.target.backendTarget.isFactoryTearOffLoweringEnabled,
ExtensionBuilder() => false,
ExtensionTypeDeclarationBuilder() => true,
};
- Reference? constructorReference;
- Reference? tearOffReference;
+ Reference? preExistingFactoryReference;
+ Reference? preExistingTearOffReference;
if (indexedContainer != null) {
- constructorReference = indexedContainer.lookupConstructorReference(
+ preExistingFactoryReference = indexedContainer.lookupConstructorReference(
nameScheme.getConstructorMemberName(name, isTearOff: false).name);
- tearOffReference = indexedContainer.lookupGetterReference(
+ preExistingTearOffReference = indexedContainer.lookupGetterReference(
nameScheme.getConstructorMemberName(name, isTearOff: true).name);
}
return new FactoryReferences._(
- constructorReference, tearOffReference, hasTearOff);
+ preExistingFactoryReference: preExistingFactoryReference,
+ preExistingTearOffReference: preExistingTearOffReference,
+ hasTearOffLowering: hasTearOffLowering);
}
+ /// Registers that [builder] is created for the pre-existing references
+ /// provided in [FactoryReferences._].
+ ///
+ /// This must be called before [factoryReference] and [tearOffReference] are
+ /// accessed.
void registerReference(SourceLoader loader, SourceFactoryBuilder builder) {
if (_factoryReference != null) {
loader.buildersCreatedWithReferences[_factoryReference!] = builder;
@@ -389,8 +415,16 @@
}
}
+ /// The [Reference] used to refer to the [Member] node created for the factory
+ /// constructor.
Reference get factoryReference => _factoryReference ??= new Reference();
- Reference get tearOffReference =>
- _tearOffReference ??= _hasTearOff ? new Reference() : factoryReference;
+ /// The [Reference] used to refer to the [Member] node created for the
+ /// tear-off of the factory constructor.
+ ///
+ /// If a tear-off lowering is created for the factory constructor, this is
+ /// distinct from [factoryReference], otherwise it is the same [Reference] as
+ /// [factoryReference].
+ Reference get tearOffReference => _tearOffReference ??=
+ _hasTearOffLowering ? new Reference() : factoryReference;
}
diff --git a/pkg/front_end/lib/src/source/source_property_builder.dart b/pkg/front_end/lib/src/source/source_property_builder.dart
index a3ab2b6..92dbe0c 100644
--- a/pkg/front_end/lib/src/source/source_property_builder.dart
+++ b/pkg/front_end/lib/src/source/source_property_builder.dart
@@ -834,36 +834,39 @@
String toString() => '$runtimeType($fullName,forSetter=${forSetter})';
}
-abstract class PropertyReferences {
- Reference? get fieldReference;
- Reference? get getterReference;
- Reference? get setterReference;
-
- void registerReference(SourceLoader loader, SourcePropertyBuilder builder);
-
- factory PropertyReferences(
- String name, NameScheme nameScheme, IndexedContainer? indexedContainer,
- {required bool fieldIsLateWithLowering}) = _PropertyReferences;
-}
-
-class _PropertyReferences implements PropertyReferences {
+/// [Reference]s used for the [Member] nodes created for a property.
+class PropertyReferences {
Reference? _fieldReference;
Reference? _getterReference;
Reference? _setterReference;
- _PropertyReferences._(
- this._fieldReference, this._getterReference, this._setterReference);
+ /// Creates a [PropertyReferences] object preloaded with the
+ /// [preExistingFieldReference], [preExistingGetterReference] and
+ /// [preExistingSetterReference].
+ ///
+ /// For initial/one-off compilations these are `null`, but for subsequent
+ /// compilations during an incremental compilation, these are the references
+ /// used for the same field, getter, and setter in the previous compilation.
+ PropertyReferences._(
+ {required Reference? preExistingFieldReference,
+ required Reference? preExistingGetterReference,
+ required Reference? preExistingSetterReference})
+ : _fieldReference = preExistingFieldReference,
+ _getterReference = preExistingGetterReference,
+ _setterReference = preExistingSetterReference;
- factory _PropertyReferences(
+ /// Creates a [PropertyReferences] object preloaded with the pre-existing
+ /// references from [indexedContainer], if available.
+ factory PropertyReferences(
String name, NameScheme nameScheme, IndexedContainer? indexedContainer,
{required bool fieldIsLateWithLowering}) {
- Reference? getterReference;
- Reference? setterReference;
- Reference? fieldReference;
+ Reference? preExistingGetterReference;
+ Reference? preExistingSetterReference;
+ Reference? preExistingFieldReference;
if (indexedContainer != null) {
Name getterNameToLookup =
nameScheme.getProcedureMemberName(ProcedureKind.Getter, name).name;
- getterReference =
+ preExistingGetterReference =
indexedContainer.lookupGetterReference(getterNameToLookup);
Name setterNameToLookup =
@@ -871,10 +874,10 @@
if ((nameScheme.isExtensionMember || nameScheme.isExtensionTypeMember) &&
nameScheme.isInstanceMember) {
// Extension (type) instance setters are encoded as methods.
- setterReference =
+ preExistingSetterReference =
indexedContainer.lookupGetterReference(setterNameToLookup);
} else {
- setterReference =
+ preExistingSetterReference =
indexedContainer.lookupSetterReference(setterNameToLookup);
}
@@ -882,14 +885,21 @@
.getFieldMemberName(FieldNameType.Field, name,
isSynthesized: fieldIsLateWithLowering)
.name;
- fieldReference = indexedContainer.lookupFieldReference(fieldNameToLookup);
+ preExistingFieldReference =
+ indexedContainer.lookupFieldReference(fieldNameToLookup);
}
- return new _PropertyReferences._(
- fieldReference, getterReference, setterReference);
+ return new PropertyReferences._(
+ preExistingFieldReference: preExistingFieldReference,
+ preExistingGetterReference: preExistingGetterReference,
+ preExistingSetterReference: preExistingSetterReference);
}
- @override
+ /// Registers that [builder] is created for the pre-existing references
+ /// provided in [PropertyReferences._].
+ ///
+ /// This must be called before [fieldReference], [getterReference] and
+ /// [setterReference] are accessed.
void registerReference(SourceLoader loader, SourcePropertyBuilder builder) {
if (_fieldReference != null) {
loader.buildersCreatedWithReferences[_fieldReference!] = builder;
@@ -902,12 +912,15 @@
}
}
- @override
+ /// The [Reference] used to refer to the field aspect of the [Field] node
+ /// created for this property.
Reference get fieldReference => _fieldReference ??= new Reference();
- @override
+ /// The [Reference] used to refer to the getter aspect of the [Member] node(s)
+ /// created for this property.
Reference get getterReference => _getterReference ??= new Reference();
- @override
+ /// The [Reference] used to refer to the setter aspect of the [Member] node(s)
+ /// created for this property.
Reference get setterReference => _setterReference ??= new Reference();
}
diff --git a/pkg/front_end/test/spell_checking_list_code.txt b/pkg/front_end/test/spell_checking_list_code.txt
index 379c22c..f53c1be 100644
--- a/pkg/front_end/test/spell_checking_list_code.txt
+++ b/pkg/front_end/test/spell_checking_list_code.txt
@@ -1343,6 +1343,7 @@
preferably
prefixing
preliminary
+preloaded
premark
preorder
prepares
