[ Service ] Update protocol documentation

Clears up confusion around function/field owner locations not
necessarily representing where the function/field was actually declared
(e.g., for functions and fields brought into a class via a mixin
application).

Fixes #45093

TEST=Documentation change

Change-Id: Ideaf17ec99d005459c60a2dd88f72b3485b32664
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/240481
Reviewed-by: Ryan Macnak <rmacnak@google.com>
Commit-Queue: Ben Konyi <bkonyi@google.com>

Author: bkonyi

pkg/vm_service/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 8.2.2+1
+- Documentation update for `FieldRef` and `FuncRef`.
+
 ## 8.2.2
 - Updated the following optional fields to be nullable in `SocketStatistic`:
   - `endTime`

pkg/vm_service/lib/src/vm_service.dart

@@ -4302,6 +4302,9 @@ class FieldRef extends ObjRef {
   String? name;
 
   /// The owner of this field, which can be either a Library or a Class.
+  ///
+  /// Note: the location of `owner` may not agree with `location` if this is a
+  /// field from a mixin application, patched class, etc.
   ObjRef? owner;
 
   /// The declared type of this field.
@@ -4320,6 +4323,9 @@ class FieldRef extends ObjRef {
   bool? isStatic;
 
   /// The location of this field in the source code.
+  ///
+  /// Note: this may not agree with the location of `owner` if this is a field
+  /// from a mixin application, patched class, etc.
   @optional
   SourceLocation? location;
 
@@ -4386,6 +4392,9 @@ class Field extends Obj implements FieldRef {
   String? name;
 
   /// The owner of this field, which can be either a Library or a Class.
+  ///
+  /// Note: the location of `owner` may not agree with `location` if this is a
+  /// field from a mixin application, patched class, etc.
   ObjRef? owner;
 
   /// The declared type of this field.
@@ -4404,6 +4413,9 @@ class Field extends Obj implements FieldRef {
   bool? isStatic;
 
   /// The location of this field in the source code.
+  ///
+  /// Note: this may not agree with the location of `owner` if this is a field
+  /// from a mixin application, patched class, etc.
   @optional
   SourceLocation? location;
 
@@ -4630,6 +4642,10 @@ class FuncRef extends ObjRef {
 
   /// The owner of this function, which can be a Library, Class, or a Function.
   ///
+  /// Note: the location of `owner` may not agree with `location` if this is a
+  /// function from a mixin application, expression evaluation, patched class,
+  /// etc.
+  ///
   /// [owner] can be one of [LibraryRef], [ClassRef] or [FuncRef].
   dynamic owner;
 
@@ -4643,6 +4659,10 @@ class FuncRef extends ObjRef {
   bool? implicit;
 
   /// The location of this function in the source code.
+  ///
+  /// Note: this may not agree with the location of `owner` if this is a
+  /// function from a mixin application, expression evaluation, patched class,
+  /// etc.
   @optional
   SourceLocation? location;
 
@@ -4706,6 +4726,10 @@ class Func extends Obj implements FuncRef {
 
   /// The owner of this function, which can be a Library, Class, or a Function.
   ///
+  /// Note: the location of `owner` may not agree with `location` if this is a
+  /// function from a mixin application, expression evaluation, patched class,
+  /// etc.
+  ///
   /// [owner] can be one of [LibraryRef], [ClassRef] or [FuncRef].
   dynamic owner;
 
@@ -4719,6 +4743,10 @@ class Func extends Obj implements FuncRef {
   bool? implicit;
 
   /// The location of this function in the source code.
+  ///
+  /// Note: this may not agree with the location of `owner` if this is a
+  /// function from a mixin application, expression evaluation, patched class,
+  /// etc.
   @optional
   SourceLocation? location;
 

pkg/vm_service/pubspec.yaml

@@ -3,7 +3,7 @@ description: >-
   A library to communicate with a service implementing the Dart VM
   service protocol.
 
-version: 8.2.2
+version: 8.2.2+1
 
 homepage: https://github.com/dart-lang/sdk/tree/master/pkg/vm_service
 

runtime/vm/service/service.md

@@ -2446,6 +2446,9 @@ class @Field extends @Object {
 
   // The owner of this field, which can be either a Library or a
   // Class.
+  //
+  // Note: the location of `owner` may not agree with `location` if this is a field
+  // from a mixin application, patched class, etc.
   @Object owner;
 
   // The declared type of this field.
@@ -2464,6 +2467,9 @@ class @Field extends @Object {
   bool static;
 
   // The location of this field in the source code.
+  //
+  // Note: this may not agree with the location of `owner` if this is a field
+  // from a mixin application, patched class, etc.
   SourceLocation location [optional];
 }
 ```
@@ -2477,6 +2483,9 @@ class Field extends Object {
 
   // The owner of this field, which can be either a Library or a
   // Class.
+  //
+  // Note: the location of `owner` may not agree with `location` if this is a field
+  // from a mixin application, patched class, etc.
   @Object owner;
 
   // The declared type of this field.
@@ -2495,6 +2504,9 @@ class Field extends Object {
   bool static;
 
   // The location of this field in the source code.
+  //
+  // Note: this may not agree with the location of `owner` if this is a field
+  // from a mixin application, patched class, etc.
   SourceLocation location [optional];
 
   // The value of this field, if the field is static. If uninitialized,
@@ -2561,6 +2573,10 @@ class @Function extends @Object {
   string name;
 
   // The owner of this function, which can be a Library, Class, or a Function.
+  //
+  // Note: the location of `owner` may not agree with `location` if this is a
+  // function from a mixin application, expression evaluation, patched class,
+  // etc.
   @Library|@Class|@Function owner;
 
   // Is this function static?
@@ -2573,6 +2589,9 @@ class @Function extends @Object {
   bool implicit;
 
   // The location of this function in the source code.
+  //
+  // Note: this may not agree with the location of `owner` if this is a function
+  // from a mixin application, expression evaluation, patched class, etc.
   SourceLocation location [optional];
 }
 ```
@@ -2586,6 +2605,10 @@ class Function extends Object {
   string name;
 
   // The owner of this function, which can be a Library, Class, or a Function.
+  //
+  // Note: the location of `owner` may not agree with `location` if this is a
+  // function from a mixin application, expression evaluation, patched class,
+  // etc.
   @Library|@Class|@Function owner;
 
   // Is this function static?
@@ -2598,6 +2621,9 @@ class Function extends Object {
   bool implicit;
 
   // The location of this function in the source code.
+  //
+  // Note: this may not agree with the location of `owner` if this is a function
+  // from a mixin application, expression evaluation, patched class, etc.
   SourceLocation location [optional];
 
   // The signature of the function.