From 8b53d26a09951805ab419f3218c0c6fa616ec761 Mon Sep 17 00:00:00 2001
From: Sam Rawlins <srawlins@google.com>
Date: Thu, 16 May 2024 19:24:38 +0000
Subject: [PATCH] observatory: replace unsupported `[this]` comment references
 with `this`.

Work towards https://github.com/dart-lang/dartdoc/issues/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.

TEST=Nope
Change-Id: Ie584a8338d4b203c4dce737769dbf2bd9094a42c
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/366881
Auto-Submit: Samuel Rawlins <srawlins@google.com>
Reviewed-by: Ben Konyi <bkonyi@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>
---
 runtime/observatory/lib/src/service/object.dart | 16 +++++++++-------
 runtime/observatory/lib/utils.dart              |  4 ++--
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/runtime/observatory/lib/src/service/object.dart b/runtime/observatory/lib/src/service/object.dart
index 38d6168b700..6949f6391f4 100644
--- a/runtime/observatory/lib/src/service/object.dart
+++ b/runtime/observatory/lib/src/service/object.dart
@@ -320,8 +320,9 @@ abstract class ServiceObject implements M.ObjectRef {
     return obj;
   }
 
-  /// If [this] was created from a reference, load the full object
-  /// from the service by calling [reload]. Else, return [this].
+  /// If this [ServiceObject] was created from a reference, load the full
+  /// object from the service by calling [reload]. Else, return this
+  /// [ServiceObject].
   Future<ServiceObject> load() {
     if (loaded) {
       return new Future.value(this);
@@ -340,8 +341,8 @@ abstract class ServiceObject implements M.ObjectRef {
     return isolate!.invokeRpcNoUpgrade('getObject', params);
   }
 
-  /// Reload [this]. Returns a future which completes to [this] or
-  /// an exception.
+  /// Reload this [ServiceObject]. Returns a future which completes to this
+  /// [ServiceObject] or an exception.
   Future<ServiceObject> reload({int count = kDefaultFieldLimit}) {
     // TODO(turnidge): Checking for a null id should be part of the
     // "immutable" check.
@@ -380,7 +381,8 @@ abstract class ServiceObject implements M.ObjectRef {
     return _inProgressReload!;
   }
 
-  /// Update [this] using [map] as a source. [map] can be a reference.
+  /// Update this [ServiceObject] using [map] as a source. [map] can be a
+  /// reference.
   void updateFromServiceMap(Map map) {
     assert(_isServiceMap(map));
 
@@ -4349,7 +4351,7 @@ class Code extends HeapObject implements M.Code {
     }
   }
 
-  /// Reload [this]. Returns a future which completes to [this] or an
+  /// Reload this [Code]. Returns a future which completes to `this` or an
   /// exception.
   Future<ServiceObject> reload({int count = kDefaultFieldLimit}) {
     assert(kind != null);
@@ -4501,7 +4503,7 @@ class Code extends HeapObject implements M.Code {
     }
   }
 
-  /// Returns true if [address] is contained inside [this].
+  /// Returns true if [address] is contained inside this [Code].
   bool contains(int address) {
     return (address >= startAddress) && (address < endAddress);
   }
diff --git a/runtime/observatory/lib/utils.dart b/runtime/observatory/lib/utils.dart
index 9921a7c1a5c..880095cef3a 100644
--- a/runtime/observatory/lib/utils.dart
+++ b/runtime/observatory/lib/utils.dart
@@ -289,8 +289,8 @@ class Task {
 
   Task(this.callback);
 
-  /// Queue [this] to run on the next Dart event queue pump. Does nothing
-  /// if [this] is already queued.
+  /// Queue this [Task] to run on the next Dart event queue pump. Does nothing
+  /// if this [Task] is already queued.
   queue() {
     if (_timer != null) {
       // Already scheduled.