macros: 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: I872c215a574dc3d04f0708387408d22fdfd14c14
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/366882
Reviewed-by: Daco Harkes <dacoharkes@google.com>
Reviewed-by: Jake Macdonald <jakemac@google.com>

pkg/_macros/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 ## Required steps when updating this package
 
-Whenever any change to the `lib` directory of this package is made, the
+When making any functional change in the `lib` directory of this package, the
 following procedure **must** be followed.
 
 ### Update pubspec/changelog for each release.
@@ -30,6 +30,12 @@ version of this package, during the pre-release period. Version compatibility is
 thus **not** guaranteed on the dev or main channels, only the beta and stable
 channels.
 
+### Bypassing presubmit checks
+
+When making a non-functional change in the `lib` directory, use the
+`--bypass-hooks` flag to bypass presubmit checks, as in
+`git cl upload --bypass-hooks`.
+
 ## Special considerations for this package
 
 This package should generally be treated like a `dart:` library, since only

pkg/_macros/lib/src/api/code.dart

@@ -457,7 +457,8 @@ final class TypeParameterCode implements Code {
 }
 
 extension Join<T extends Object> on List<T> {
-  /// Joins all the items in [this] with [separator], and returns a new list.
+  /// Joins all the items in this [Join] with [separator], and returns a new
+  /// list.
   ///
   /// Works on any kind of non-nullable list which accepts String entries, and
   /// does not convert the individual items to strings.

pkg/front_end/testcases/incremental/macro_change_entry_one.yaml.world.1.expect

@@ -49,7 +49,7 @@ holepunch:pkg/_macros/lib/src/api/builders.dart:
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 
 holepunch:pkg/_macros/lib/src/api/code.dart:
-- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:473:6)
+- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:474:6)
 - _Enum. (from org-dartlang-sdk:///sdk/lib/core/enum.dart)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 

pkg/front_end/testcases/incremental/macro_change_entry_one.yaml.world.2.expect

@@ -36,7 +36,7 @@ holepunch:pkg/_macros/lib/src/api/builders.dart:
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 
 holepunch:pkg/_macros/lib/src/api/code.dart:
-- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:473:6)
+- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:474:6)
 - _Enum. (from org-dartlang-sdk:///sdk/lib/core/enum.dart)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 

pkg/front_end/testcases/incremental/macro_change_entry_two.yaml.world.1.expect

@@ -49,7 +49,7 @@ holepunch:pkg/_macros/lib/src/api/builders.dart:
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 
 holepunch:pkg/_macros/lib/src/api/code.dart:
-- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:473:6)
+- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:474:6)
 - _Enum. (from org-dartlang-sdk:///sdk/lib/core/enum.dart)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 

pkg/front_end/testcases/incremental/macro_change_entry_two.yaml.world.2.expect

@@ -45,7 +45,7 @@ holepunch:pkg/_macros/lib/src/api/builders.dart:
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 
 holepunch:pkg/_macros/lib/src/api/code.dart:
-- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:473:6)
+- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:474:6)
 - _Enum. (from org-dartlang-sdk:///sdk/lib/core/enum.dart)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 

pkg/front_end/testcases/incremental/macro_change_nestedness.yaml.world.1.expect

@@ -69,7 +69,7 @@ holepunch:pkg/_macros/lib/src/api/builders.dart:
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 
 holepunch:pkg/_macros/lib/src/api/code.dart:
-- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:473:6)
+- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:474:6)
 - _Enum. (from org-dartlang-sdk:///sdk/lib/core/enum.dart)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 

pkg/front_end/testcases/incremental/macro_change_nestedness.yaml.world.2.expect

@@ -84,7 +84,7 @@ holepunch:pkg/_macros/lib/src/api/builders.dart:
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 
 holepunch:pkg/_macros/lib/src/api/code.dart:
-- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:473:6)
+- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:474:6)
 - _Enum. (from org-dartlang-sdk:///sdk/lib/core/enum.dart)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 

pkg/front_end/testcases/incremental/macro_recompile.yaml.world.1.expect

@@ -69,7 +69,7 @@ holepunch:pkg/_macros/lib/src/api/builders.dart:
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 
 holepunch:pkg/_macros/lib/src/api/code.dart:
-- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:473:6)
+- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:474:6)
 - _Enum. (from org-dartlang-sdk:///sdk/lib/core/enum.dart)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 

pkg/front_end/testcases/incremental/macro_recompile.yaml.world.2.expect

@@ -66,7 +66,7 @@ holepunch:pkg/_macros/lib/src/api/builders.dart:
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 
 holepunch:pkg/_macros/lib/src/api/code.dart:
-- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:473:6)
+- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:474:6)
 - _Enum. (from org-dartlang-sdk:///sdk/lib/core/enum.dart)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 

pkg/front_end/testcases/incremental/macro_reuse_compiled_macro.yaml.world.1.expect

@@ -68,7 +68,7 @@ holepunch:pkg/_macros/lib/src/api/builders.dart:
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 
 holepunch:pkg/_macros/lib/src/api/code.dart:
-- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:473:6)
+- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:474:6)
 - _Enum. (from org-dartlang-sdk:///sdk/lib/core/enum.dart)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 

pkg/front_end/testcases/incremental/macro_reuse_compiled_macro.yaml.world.2.expect

@@ -65,7 +65,7 @@ holepunch:pkg/_macros/lib/src/api/builders.dart:
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)
 
 holepunch:pkg/_macros/lib/src/api/code.dart:
-- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:473:6)
+- CodeKind. (from holepunch:pkg/_macros/lib/src/api/code.dart:474:6)
 - _Enum. (from org-dartlang-sdk:///sdk/lib/core/enum.dart)
 - Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart)