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

Work towards dart-lang/dartdoc#3761

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.

CoreLibraryReviewExempt: Comments only.
Change-Id: I6cc85115186527820bdd38dcfda8f61e35ae3fe9
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/365204
Reviewed-by: Nate Bosch <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>
Reviewed-by: Lasse Nielsen <[email protected]>

Author: srawlins

sdk/lib/_internal/js_dev_runtime/patch/bigint_patch.dart

@@ -1940,7 +1940,7 @@ class _BigIntImpl implements BigInt {
     return _a + digit - 10;
   }
 
-  /// Converts [this] to a string representation in the given [radix].
+  /// Converts this [BigInt] to a string representation in the given [radix].
   ///
   /// In the string representation, lower-case letters are used for digits above
   /// '9', with 'a' being 10 an 'z' being 35.

sdk/lib/_internal/js_dev_runtime/private/js_array.dart

@@ -143,7 +143,7 @@ class JSArray<E> extends JavaScriptObject
     return false;
   }
 
-  /// Removes elements matching [test] from [this] List.
+  /// Removes elements matching [test] from this [JSArray].
   void removeWhere(bool Function(E) test) {
     checkGrowable('removeWhere');
     _removeWhere(test, true);

sdk/lib/_internal/js_dev_runtime/private/native_typed_data.dart

@@ -1272,7 +1272,7 @@ final class NativeFloat32x4 implements Float32x4 {
         _cx ? -1 : 0, _cy ? -1 : 0, _cz ? -1 : 0, _cw ? -1 : 0);
   }
 
-  /// Returns a copy of [this] each lane being scaled by [s].
+  /// Returns a copy of this [Float32x4] each lane being scaled by [s].
   Float32x4 scale(double s) {
     double _x = s * x;
     double _y = s * y;
@@ -1290,7 +1290,7 @@ final class NativeFloat32x4 implements Float32x4 {
     return NativeFloat32x4._truncated(_x, _y, _z, _w);
   }
 
-  /// Clamps [this] to be in the range [lowerLimit]-[upperLimit].
+  /// Clamps this [Float32x4] to be in the range [lowerLimit]-[upperLimit].
   Float32x4 clamp(Float32x4 lowerLimit, Float32x4 upperLimit) {
     double _lx = lowerLimit.x;
     double _ly = lowerLimit.y;
@@ -1349,9 +1349,9 @@ final class NativeFloat32x4 implements Float32x4 {
     return NativeFloat32x4._truncated(_x, _y, _z, _w);
   }
 
-  /// Shuffle the lane values in [this] and [other]. The returned
-  /// Float32x4 will have XY lanes from [this] and ZW lanes from [other].
-  /// Uses the same [mask] as [shuffle].
+  /// Shuffle the lane values in this [Float32x4] and [other]. The returned
+  /// Float32x4 will have XY lanes from this [Float32x4] and ZW lanes from
+  /// [other]. Uses the same [mask] as [shuffle].
   Float32x4 shuffleMix(Float32x4 other, int mask) {
     if ((mask < 0) || (mask > 255)) {
       throw RangeError.range(mask, 0, 255, "mask");
@@ -1372,31 +1372,31 @@ final class NativeFloat32x4 implements Float32x4 {
     return NativeFloat32x4._truncated(_x, _y, _z, _w);
   }
 
-  /// Copy [this] and replace the [x] lane.
+  /// Copy this [Float32x4] and replace the [x] lane.
   Float32x4 withX(double newX) {
     ArgumentError.checkNotNull(newX);
     return NativeFloat32x4._truncated(_truncate(newX), y, z, w);
   }
 
-  /// Copy [this] and replace the [y] lane.
+  /// Copy this [Float32x4] and replace the [y] lane.
   Float32x4 withY(double newY) {
     ArgumentError.checkNotNull(newY);
     return NativeFloat32x4._truncated(x, _truncate(newY), z, w);
   }
 
-  /// Copy [this] and replace the [z] lane.
+  /// Copy this [Float32x4] and replace the [z] lane.
   Float32x4 withZ(double newZ) {
     ArgumentError.checkNotNull(newZ);
     return NativeFloat32x4._truncated(x, y, _truncate(newZ), w);
   }
 
-  /// Copy [this] and replace the [w] lane.
+  /// Copy this [Float32x4] and replace the [w] lane.
   Float32x4 withW(double newW) {
     ArgumentError.checkNotNull(newW);
     return NativeFloat32x4._truncated(x, y, z, _truncate(newW));
   }
 
-  /// Returns the lane-wise minimum value in [this] or [other].
+  /// Returns the lane-wise minimum value in this [Float32x4] or [other].
   Float32x4 min(Float32x4 other) {
     double _x = x < other.x ? x : other.x;
     double _y = y < other.y ? y : other.y;
@@ -1405,7 +1405,7 @@ final class NativeFloat32x4 implements Float32x4 {
     return NativeFloat32x4._truncated(_x, _y, _z, _w);
   }
 
-  /// Returns the lane-wise maximum value in [this] or [other].
+  /// Returns the lane-wise maximum value in this [Float32x4] or [other].
   Float32x4 max(Float32x4 other) {
     double _x = x > other.x ? x : other.x;
     double _y = y > other.y ? y : other.y;
@@ -1414,7 +1414,7 @@ final class NativeFloat32x4 implements Float32x4 {
     return NativeFloat32x4._truncated(_x, _y, _z, _w);
   }
 
-  /// Returns the square root of [this].
+  /// Returns the square root of this [Float32x4].
   Float32x4 sqrt() {
     double _x = Math.sqrt(x);
     double _y = Math.sqrt(y);
@@ -1423,7 +1423,7 @@ final class NativeFloat32x4 implements Float32x4 {
     return NativeFloat32x4._doubles(_x, _y, _z, _w);
   }
 
-  /// Returns the reciprocal of [this].
+  /// Returns the reciprocal of this [Float32x4].
   Float32x4 reciprocal() {
     double _x = 1.0 / x;
     double _y = 1.0 / y;
@@ -1432,7 +1432,7 @@ final class NativeFloat32x4 implements Float32x4 {
     return NativeFloat32x4._doubles(_x, _y, _z, _w);
   }
 
-  /// Returns the square root of the reciprocal of [this].
+  /// Returns the square root of the reciprocal of this [Float32x4].
   Float32x4 reciprocalSqrt() {
     double _x = Math.sqrt(1.0 / x);
     double _y = Math.sqrt(1.0 / y);
@@ -1577,8 +1577,8 @@ final class NativeInt32x4 implements Int32x4 {
     return NativeInt32x4._truncated(_x, _y, _z, _w);
   }
 
-  /// Shuffle the lane values in [this] and [other]. The returned
-  /// Int32x4 will have XY lanes from [this] and ZW lanes from [other].
+  /// Shuffle the lane values in this [Int32x4] and [other]. The returned
+  /// Int32x4 will have XY lanes from this [Int32x4] and ZW lanes from [other].
   /// Uses the same [mask] as [shuffle].
   Int32x4 shuffleMix(Int32x4 other, int mask) {
     if ((mask < 0) || (mask > 255)) {
@@ -1600,28 +1600,28 @@ final class NativeInt32x4 implements Int32x4 {
     return NativeInt32x4._truncated(_x, _y, _z, _w);
   }
 
-  /// Returns a new [Int32x4] copied from [this] with a new x value.
+  /// Returns a new [Int32x4] copied from this [Int32x4] with a new x value.
   Int32x4 withX(int x) {
     ArgumentError.checkNotNull(x);
     int _x = _truncate(x);
     return NativeInt32x4._truncated(_x, y, z, w);
   }
 
-  /// Returns a new [Int32x4] copied from [this] with a new y value.
+  /// Returns a new [Int32x4] copied from this [Int32x4] with a new y value.
   Int32x4 withY(int y) {
     ArgumentError.checkNotNull(y);
     int _y = _truncate(y);
     return NativeInt32x4._truncated(x, _y, z, w);
   }
 
-  /// Returns a new [Int32x4] copied from [this] with a new z value.
+  /// Returns a new [Int32x4] copied from this [Int32x4] with a new z value.
   Int32x4 withZ(int z) {
     ArgumentError.checkNotNull(z);
     int _z = _truncate(z);
     return NativeInt32x4._truncated(x, y, _z, w);
   }
 
-  /// Returns a new [Int32x4] copied from [this] with a new w value.
+  /// Returns a new [Int32x4] copied from this [Int32x4] with a new w value.
   Int32x4 withW(int w) {
     ArgumentError.checkNotNull(w);
     int _w = _truncate(w);
@@ -1640,33 +1640,33 @@ final class NativeInt32x4 implements Int32x4 {
   /// Extracted w value. Returns `false` for 0, `true` for any other value.
   bool get flagW => w != 0;
 
-  /// Returns a new [Int32x4] copied from [this] with a new x value.
+  /// Returns a new [Int32x4] copied from this [Int32x4] with a new x value.
   Int32x4 withFlagX(bool flagX) {
     int _x = flagX ? -1 : 0;
     return NativeInt32x4._truncated(_x, y, z, w);
   }
 
-  /// Returns a new [Int32x4] copied from [this] with a new y value.
+  /// Returns a new [Int32x4] copied from this [Int32x4] with a new y value.
   Int32x4 withFlagY(bool flagY) {
     int _y = flagY ? -1 : 0;
     return NativeInt32x4._truncated(x, _y, z, w);
   }
 
-  /// Returns a new [Int32x4] copied from [this] with a new z value.
+  /// Returns a new [Int32x4] copied from this [Int32x4] with a new z value.
   Int32x4 withFlagZ(bool flagZ) {
     int _z = flagZ ? -1 : 0;
     return NativeInt32x4._truncated(x, y, _z, w);
   }
 
-  /// Returns a new [Int32x4] copied from [this] with a new w value.
+  /// Returns a new [Int32x4] copied from this [Int32x4] with a new w value.
   Int32x4 withFlagW(bool flagW) {
     int _w = flagW ? -1 : 0;
     return NativeInt32x4._truncated(x, y, z, _w);
   }
 
-  /// Merge [trueValue] and [falseValue] based on [this]' bit mask:
-  /// Select bit from [trueValue] when bit in [this] is on.
-  /// Select bit from [falseValue] when bit in [this] is off.
+  /// Merge [trueValue] and [falseValue] based on this [Int32x4] bit mask:
+  /// Select bit from [trueValue] when bit in this [Int32x4] is on.
+  /// Select bit from [falseValue] when bit in this [Int32x4] is off.
   Float32x4 select(Float32x4 trueValue, Float32x4 falseValue) {
     var floatList = NativeFloat32x4._list;
     var intView = NativeFloat32x4._uint32view;
@@ -1749,7 +1749,7 @@ final class NativeFloat64x2 implements Float64x2 {
     return NativeFloat64x2._doubles(x / other.x, y / other.y);
   }
 
-  /// Returns a copy of [this] each lane being scaled by [s].
+  /// Returns a copy of this [Float64x2] each lane being scaled by [s].
   Float64x2 scale(double s) {
     return NativeFloat64x2._doubles(x * s, y * s);
   }
@@ -1759,7 +1759,7 @@ final class NativeFloat64x2 implements Float64x2 {
     return NativeFloat64x2._doubles(x.abs(), y.abs());
   }
 
-  /// Clamps [this] to be in the range [lowerLimit]-[upperLimit].
+  /// Clamps this [Float64x2] to be in the range [lowerLimit]-[upperLimit].
   Float64x2 clamp(Float64x2 lowerLimit, Float64x2 upperLimit) {
     double _lx = lowerLimit.x;
     double _ly = lowerLimit.y;
@@ -1785,31 +1785,33 @@ final class NativeFloat64x2 implements Float64x2 {
     return mx | my << 1;
   }
 
-  /// Returns a new [Float64x2] copied from [this] with a new x value.
+  /// Returns a new [Float64x2] copied from this [Float64x2] with a new x
+  /// value.
   Float64x2 withX(double x) {
     if (x is! num) throw ArgumentError(x);
     return NativeFloat64x2._doubles(x, y);
   }
 
-  /// Returns a new [Float64x2] copied from [this] with a new y value.
+  /// Returns a new [Float64x2] copied from this [Float64x2] with a new y
+  /// value.
   Float64x2 withY(double y) {
     if (y is! num) throw ArgumentError(y);
     return NativeFloat64x2._doubles(x, y);
   }
 
-  /// Returns the lane-wise minimum value in [this] or [other].
+  /// Returns the lane-wise minimum value in this [Float64x2] or [other].
   Float64x2 min(Float64x2 other) {
     return NativeFloat64x2._doubles(
         x < other.x ? x : other.x, y < other.y ? y : other.y);
   }
 
-  /// Returns the lane-wise maximum value in [this] or [other].
+  /// Returns the lane-wise maximum value in this [Float64x2] or [other].
   Float64x2 max(Float64x2 other) {
     return NativeFloat64x2._doubles(
         x > other.x ? x : other.x, y > other.y ? y : other.y);
   }
 
-  /// Returns the lane-wise square root of [this].
+  /// Returns the lane-wise square root of this [Float64x2].
   Float64x2 sqrt() {
     return NativeFloat64x2._doubles(Math.sqrt(x), Math.sqrt(y));
   }

sdk/lib/_internal/js_runtime/lib/async_patch.dart

@@ -556,7 +556,7 @@ class _SyncStarIterator<T> implements Iterator<T> {
   // statements. For non-sync* iterators, [_nestedIterator] contains the
   // iterator. We delegate to [_nestedIterator] when it is not `null`.
   //
-  // For nested sync* iterators, [this] iterator acts on behalf of the innermost
+  // For nested sync* iterators, this [Iterator] acts on behalf of the innermost
   // nested sync* iterator. The current state machine is suspended on a stack
   // until the inner state machine ends.
 

sdk/lib/_internal/js_runtime/lib/bigint_patch.dart

@@ -1959,7 +1959,7 @@ class _BigIntImpl implements BigInt {
     return _a + digit - 10;
   }
 
-  /// Converts [this] to a string representation in the given [radix].
+  /// Converts this [BigInt] to a string representation in the given [radix].
   ///
   /// In the string representation, lower-case letters are used for digits above
   /// '9', with 'a' being 10 an 'z' being 35.

sdk/lib/_internal/js_runtime/lib/js_array.dart

@@ -225,7 +225,7 @@ class JSArray<E> extends JavaScriptObject implements List<E>, JSIndexable<E> {
     return false;
   }
 
-  /// Removes elements matching [test] from [this] List.
+  /// Removes elements matching [test] from this [JSArray].
   void removeWhere(bool test(E element)) {
     checkGrowable('removeWhere');
     _removeWhere(test, true);