[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>

pkg/front_end/lib/src/fragment/enum_element.dart

@@ -258,7 +258,7 @@ class EnumElementDeclaration
   // Coverage-ignore(suite): Not run.
   Iterable<Reference> getExportedGetterReferences(
       PropertyReferences references) {
-    return [references.getterReference!];
+    return [references.getterReference];
   }
 
   @override

pkg/front_end/lib/src/fragment/field/declaration.dart

@@ -693,13 +693,13 @@ class RegularFieldDeclaration
   @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 [];
   }
 }
 

pkg/front_end/lib/src/fragment/getter/declaration.dart

@@ -253,7 +253,7 @@ class RegularGetterDeclaration
   @override
   Iterable<Reference> getExportedGetterReferences(
           PropertyReferences references) =>
-      [references.getterReference!];
+      [references.getterReference];
 
   @override
   VariableDeclaration getFormalParameter(int index) {

pkg/front_end/lib/src/fragment/primary_constructor_field.dart

@@ -340,7 +340,7 @@ class PrimaryConstructorFieldDeclaration
   // Coverage-ignore(suite): Not run.
   Iterable<Reference> getExportedGetterReferences(
       PropertyReferences references) {
-    return [references.getterReference!];
+    return [references.getterReference];
   }
 
   @override

pkg/front_end/lib/src/fragment/setter/declaration.dart

@@ -255,7 +255,7 @@ class RegularSetterDeclaration
   @override
   Iterable<Reference> getExportedSetterReferences(
           PropertyReferences references) =>
-      [references.setterReference!];
+      [references.setterReference];
 
   @override
   VariableDeclaration getFormalParameter(int index) {

pkg/front_end/lib/src/source/source_constructor_builder.dart

@@ -593,16 +593,36 @@ class SourceConstructorBuilder extends SourceMemberBuilderImpl
   }
 }
 
+/// [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 @@ class ConstructorReferences {
     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 @@ class ConstructorReferences {
       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 @@ class ConstructorReferences {
     }
   }
 
+  /// 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;
 }

pkg/front_end/lib/src/source/source_enum_builder.dart

@@ -861,7 +861,7 @@ class _EnumValuesFieldDeclaration
   // Coverage-ignore(suite): Not run.
   Iterable<Reference> getExportedGetterReferences(
       PropertyReferences references) {
-    return [references.getterReference!];
+    return [references.getterReference];
   }
 }
 

pkg/front_end/lib/src/source/source_factory_builder.dart

@@ -342,16 +342,35 @@ class InferableRedirectingFactory implements InferableMember {
   }
 }
 
+/// [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 @@ class FactoryReferences {
     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 @@ class FactoryReferences {
     }
   }
 
+  /// 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;
 }

pkg/front_end/lib/src/source/source_property_builder.dart

@@ -834,36 +834,39 @@ class SetterClassMember implements ClassMember {
   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 @@ class _PropertyReferences implements PropertyReferences {
       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 @@ class _PropertyReferences implements PropertyReferences {
           .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 @@ class _PropertyReferences implements PropertyReferences {
     }
   }
 
-  @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();
 }

pkg/front_end/test/spell_checking_list_code.txt

@@ -1343,6 +1343,7 @@ preexisting
 preferably
 prefixing
 preliminary
+preloaded
 premark
 preorder
 prepares