compiler: replace unsupported [this] comment references with this.

Work towards dart-lang/dartdoc#3761

Sibling CL to https://dart-review.googlesource.com/c/sdk/+/365204

The analyzer has never recognized `[this]` as a valid doc comment
reference (and the `comment_references` lint rule has similarly
reported such reference attempts). dartdoc has its own algorithms
for resolving comment references, which we are dismantling in favor
of a single resolution, provided by the analyzer.

We've also decided against adding support in the analyzer (see
https://github.com/dart-lang/linter/issues/2079), so these
reference attempts should be re-written.

Change-Id: I0a30a34c9f58bd6c98c6b83e607a973c9ba51ed7
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/366900
Commit-Queue: Samuel Rawlins <[email protected]>
Auto-Submit: Samuel Rawlins <[email protected]>
Reviewed-by: Mayank Patke <[email protected]>

pkg/compiler/lib/src/closure.dart

@@ -341,7 +341,7 @@ class TypeVariableLocal implements Local {
   }
 }
 
-/// A local variable used encode the direct (uncaptured) references to [this].
+/// A local variable used to encode the direct (uncaptured) references to `this`.
 class ThisLocal extends Local {
   final ClassEntity enclosingClass;
 

pkg/compiler/lib/src/inferrer/type_graph_nodes.dart

@@ -1042,7 +1042,8 @@ abstract class CallSiteTypeInformation extends TypeInformation
   @override
   String toString() => 'Call site $debugName $type';
 
-  /// Add [this] to the graph being computed by [engine].
+  /// Add this [CallSiteTypeInformation] to the graph being computed by
+  /// [engine].
   void addToGraph(InferrerEngine engine);
 
   String get debugName => '$callNode';

pkg/compiler/lib/src/inferrer/typemasks/type_mask.dart

@@ -337,13 +337,13 @@ abstract class TypeMask implements AbstractValue {
     return 'Unknown type mask $mask.';
   }
 
-  /// Returns a nullable variant of [this] type mask.
+  /// Returns a nullable variant of this [TypeMask].
   TypeMask nullable() => withFlags(isNullable: true);
 
-  /// Returns a non-nullable variant of [this] type mask.
+  /// Returns a non-nullable variant of this [TypeMask].
   TypeMask nonNullable() => withFlags(isNullable: false);
 
-  /// Returns a variant of [this] type mask whose value is neither `null` nor
+  /// Returns a variant of this [TypeMask] whose value is neither `null` nor
   /// the late sentinel.
   TypeMask withoutFlags() =>
       withFlags(isNullable: false, hasLateSentinel: false);
@@ -359,14 +359,14 @@ abstract class TypeMask implements AbstractValue {
   /// Whether the only possible value in this mask is Null.
   bool get isNull;
 
-  /// Whether [this] is a sentinel for an uninitialized late variable.
+  /// Whether this [TypeMask] is a sentinel for an uninitialized late variable.
   AbstractBool get isLateSentinel;
 
   /// Whether a late sentinel is a valid value of this mask.
   bool get hasLateSentinel => isLateSentinel.isPotentiallyTrue;
 
-  /// Whether [this] mask is empty or only represents values tracked by flags
-  /// (i.e. `null` and the late sentinel).
+  /// Whether this [TypeMask] is empty or only represents values tracked by
+  /// flags (i.e. `null` and the late sentinel).
   bool get isEmptyOrFlagged;
 
   /// Whether this mask only includes instances of an exact class, and none of
@@ -411,13 +411,15 @@ abstract class TypeMask implements AbstractValue {
   /// otherwise returns `null`.  This method is conservative.
   ClassEntity? singleClass(JClosedWorld closedWorld);
 
-  /// Returns a type mask representing the union of [this] and [other].
+  /// Returns a type mask representing the union of this [TypeMask] and
+  /// [other].
   TypeMask union(TypeMask other, CommonMasks domain);
 
   /// Returns whether the intersection of this and [other] is empty.
   bool isDisjoint(TypeMask other, JClosedWorld closedWorld);
 
-  /// Returns a type mask representing the intersection of [this] and [other].
+  /// Returns a type mask representing the intersection of this [TypeMask] and
+  /// [other].
   TypeMask intersection(TypeMask other, CommonMasks domain);
 
   /// Returns whether [element] is a potential target when being invoked on this

pkg/compiler/lib/src/ssa/optimize.dart

@@ -4254,7 +4254,8 @@ class MemorySet {
     }
   }
 
-  /// Returns the intersection between [this] and the [other] memory set.
+  /// Returns the intersection between this [MemorySet] and the [other] memory
+  /// set.
   MemorySet intersectionFor(
       MemorySet? other, HBasicBlock block, int predecessorIndex) {
     MemorySet result = MemorySet(closedWorld);
@@ -4335,7 +4336,7 @@ class MemorySet {
     return result;
   }
 
-  /// Returns a copy of [this] memory set.
+  /// Returns a copy of this [MemorySet].
   MemorySet clone() {
     MemorySet result = MemorySet(closedWorld);
 
@@ -4351,7 +4352,7 @@ class MemorySet {
     return result;
   }
 
-  /// Returns a copy of [this] memory set, removing any expressions that are not
+  /// Returns a copy of this [MemorySet], removing any expressions that are not
   /// valid in [block].
   MemorySet cloneIfDominatesBlock(HBasicBlock block) {
     bool instructionDominatesBlock(HInstruction? instruction) {

pkg/compiler/lib/src/universe/selector.dart

@@ -239,7 +239,8 @@ class Selector {
     return signatureApplies(element as FunctionEntity);
   }
 
-  /// Whether [this] could be a valid selector on `Null` without throwing.
+  /// Whether this [Selector] could be a valid selector on `Null` without
+  /// throwing.
   bool appliesToNullWithoutThrow() {
     var name = this.name;
     if (isOperator && name == "==") return true;