Elements. Add documentationComment and metadata to Element and Fragment.

Bug: #61216
Change-Id: I46ee0dfe2a720d61b3b4576634cf623b8817d0ac
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/443149
Reviewed-by: Johnni Winther <[email protected]>
Reviewed-by: Brian Wilkerson <[email protected]>
Commit-Queue: Konstantin Shcheglov <[email protected]>

Author: scheglov

pkg/analysis_server/lib/plugin/protocol/protocol_dart.dart

@@ -24,9 +24,7 @@ Element convertElement(engine.Element element) {
     name,
     Element.makeFlags(
       isPrivate: element.isPrivate,
-      isDeprecated:
-          (element is engine.Annotatable) &&
-          (element as engine.Annotatable).metadata.hasDeprecated,
+      isDeprecated: element.metadata.hasDeprecated,
       isAbstract: _isAbstract(element),
       isConst: _isConst(element),
       isFinal: _isFinal(element),

pkg/analysis_server/lib/src/computer/computer_documentation.dart

@@ -3,7 +3,6 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'package:analysis_server/src/computer/computer_overrides.dart';
-import 'package:analysis_server/src/utilities/extensions/element.dart';
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/src/dartdoc/dartdoc_directive_info.dart';
 
@@ -36,7 +35,7 @@ class DartDocumentationComputer {
       if (element case PropertyAccessorElement(:var variable)) variable,
     ];
     for (var candidate in candidates) {
-      if (candidate.documentationCommentOrNull != null) {
+      if (candidate.documentationComment != null) {
         documentedElement = candidate;
         break;
       }
@@ -54,7 +53,7 @@ class DartDocumentationComputer {
       return null;
     }
 
-    var rawDoc = documentedElement.documentationCommentOrNull;
+    var rawDoc = documentedElement.documentationComment;
     if (rawDoc == null) {
       return null;
     }

pkg/analysis_server/lib/src/computer/computer_hover.dart

@@ -67,9 +67,7 @@ class DartUnitHoverComputer {
         // short code that illustrates the element meaning.
         hover.elementDescription = _elementDisplayString(node, element);
         hover.elementKind = element.kind.displayName;
-        if (element case Annotatable a) {
-          hover.isDeprecated = a.metadata.hasDeprecated;
-        }
+        hover.isDeprecated = element.metadata.hasDeprecated;
         // not local element
         if (element.enclosingElement is! ExecutableElement) {
           // containing class

pkg/analysis_server/lib/src/lsp/completion_utils.dart

@@ -689,8 +689,7 @@ CompletionDetail _getCompletionDetail(
   // Use the full signature in the details popup.
   var detail = fullSignature;
   if (element != null &&
-      (element is Annotatable &&
-          (element as Annotatable).metadata.hasDeprecated) &&
+      element.metadata.hasDeprecated &&
       !supportsDeprecated) {
     // If the item is deprecated and we don't support the native deprecated flag
     // then include it in the details.

pkg/analysis_server/lib/src/lsp/handlers/custom/editable_arguments/editable_arguments_mixin.dart

@@ -221,8 +221,8 @@ extension on InvocationExpressionImpl {
       _ => null,
     };
 
-    if (element case Annotatable annotatable) {
-      return annotatable.metadata.hasWidgetFactory;
+    if (element != null) {
+      return element.metadata.hasWidgetFactory;
     }
     return false;
   }

pkg/analysis_server/lib/src/status/utilities/element_writer.dart

@@ -36,9 +36,7 @@ class ElementWriter with TreeWriter {
   Map<String, Object?> _computeProperties(Element element) {
     var properties = <String, Object?>{};
 
-    if (element case Annotatable element) {
-      properties['annotations'] = element.metadata.annotations;
-    }
+    properties['annotations'] = element.metadata.annotations;
     if (element is InterfaceElement) {
       properties['interfaces'] = element.interfaces;
       properties['isEnum'] = element is EnumElement;

pkg/analysis_server/lib/src/utilities/extensions/element.dart

@@ -23,29 +23,12 @@ extension ClassElementExtensions on ClassElement {
 }
 
 extension ElementExtensions on Element {
-  /// The content of the documentation comment (including delimiters) for this
-  /// element.
-  ///
-  /// If the receiver is an element that has fragments, the comment will be a
-  /// concatenation of the comments from all of the fragments.
-  ///
-  /// Returns `null` if the receiver does not have or does not support
-  /// documentation.
-  String? get documentationCommentOrNull {
-    return switch (this) {
-      Annotatable(:var documentationComment) => documentationComment,
-      _ => null,
-    };
-  }
-
   /// Return `true` if this element, the enclosing class (if there is one), or
   /// the enclosing library, has been annotated with the `@deprecated`
   /// annotation.
   bool get hasOrInheritsDeprecated {
-    if (this case Annotatable annotatable) {
-      if (annotatable.metadata.hasDeprecated) {
-        return true;
-      }
+    if (metadata.hasDeprecated) {
+      return true;
     }
 
     var ancestor = enclosingElement;

pkg/analyzer/CHANGELOG.md

@@ -1,6 +1,8 @@
 ## 8.1.0-dev
 * Add `DartObject.constructorInvocation` with the constructor and arguments.
 * Make `PropertyAccessorElement.variable` non-nullable.
+* Add `documentationComment` to `Element` and `Fragment`.
+* Add `metadata` to `Element` and `Fragment`.`
 * Fix draining analysis events when used by `package:build`.
 * Deprecate `LibraryElementResult.element2`, use `element` instead.
 * Deprecate `ResolvedLibraryResult.element2`, use `element` instead.
@@ -10,6 +12,7 @@
 * Deprecate `resolveFile2`, use `resolveFile` instead.
 * Deprecate `DartObject.variable2`, use `variable` instead.
 * Deprecate `DartObject.toFunctionValue2`, use `toFunctionValue` instead.
+* Deprecate `Annotatable`, use `documentationComment` and `metadata` of `Element` or `Fragment` directly.
 
 ## 8.0.0
 * Remove deprecated element model V1.

pkg/analyzer/api.txt

@@ -3283,7 +3283,7 @@ package:analyzer/dart/constant/value.dart:
     toSymbolValue (method: String? Function())
     toTypeValue (method: DartType? Function())
 package:analyzer/dart/element/element.dart:
-  Annotatable (class extends Object):
+  Annotatable (class extends Object, deprecated):
     new (constructor: Annotatable Function())
     documentationComment (getter: String?)
     metadata (getter: Metadata)
@@ -3379,6 +3379,7 @@ package:analyzer/dart/element/element.dart:
     children (getter: List<Element>)
     children2 (getter: List<Element>, deprecated)
     displayName (getter: String)
+    documentationComment (getter: String?)
     enclosingElement (getter: Element?)
     enclosingElement2 (getter: Element?, deprecated)
     firstFragment (getter: Fragment)
@@ -3391,6 +3392,7 @@ package:analyzer/dart/element/element.dart:
     library (getter: LibraryElement?)
     library2 (getter: LibraryElement?, deprecated)
     lookupName (getter: String?)
+    metadata (getter: Metadata)
     name (getter: String?)
     name3 (getter: String?, deprecated)
     nonSynthetic (getter: Element)
@@ -3648,9 +3650,11 @@ package:analyzer/dart/element/element.dart:
     new (constructor: Fragment Function())
     children (getter: List<Fragment>)
     children3 (getter: List<Fragment>, deprecated)
+    documentationComment (getter: String?)
     element (getter: Element)
     enclosingFragment (getter: Fragment?)
     libraryFragment (getter: LibraryFragment?)
+    metadata (getter: Metadata)
     name (getter: String?)
     name2 (getter: String?, deprecated)
     nameOffset (getter: int?)

pkg/analyzer/lib/dart/element/element.dart

@@ -165,6 +165,7 @@ typedef VariableElement2 = VariableElement;
 
 /// An element or fragment that can have either annotations (metadata), a
 /// documentation comment, or both associated with it.
+@Deprecated('Use Element or Fragment directly instead')
 abstract class Annotatable {
   /// The content of the documentation comment (including delimiters) for this
   /// element or fragment.
@@ -600,6 +601,14 @@ abstract class Element {
   /// but the `displayName` is `s`.
   String get displayName;
 
+  /// The content of the documentation comment (including delimiters) for this
+  /// element.
+  ///
+  /// This is a concatenation of the comments from all of the fragments.
+  ///
+  /// Returns `null` if the element doesn't have documentation.
+  String? get documentationComment;
+
   /// The element that either physically or logically encloses this element.
   ///
   /// Returns `null` if this element is a library because libraries are the
@@ -676,6 +685,13 @@ abstract class Element {
   /// For a binary operator `-` the result is just `-`.
   String? get lookupName;
 
+  /// The metadata associated with the element.
+  ///
+  /// It includes all annotations from all of the fragments.
+  ///
+  /// The list will be empty if the element does not have any metadata.
+  Metadata get metadata;
+
   /// The name of this element.
   ///
   /// Returns `null` if this element doesn't have a name.
@@ -1012,7 +1028,10 @@ abstract class ElementAnnotation {
 /// A directive within a library fragment.
 ///
 /// Clients may not extend, implement or mix-in this class.
-abstract class ElementDirective implements Annotatable {
+abstract class ElementDirective
+    implements
+        Annotatable // ignore:deprecated_member_use_from_same_package
+        {
   /// The library fragment that contains this object.
   LibraryFragment get libraryFragment;
 
@@ -1581,7 +1600,10 @@ abstract class FieldFragment implements PropertyInducingFragment {
 ///
 /// Clients may not extend, implement or mix-in this class.
 abstract class FormalParameterElement
-    implements VariableElement, Annotatable, LocalElement {
+    implements
+        VariableElement,
+        Annotatable, // ignore:deprecated_member_use_from_same_package
+        LocalElement {
   @override
   FormalParameterElement get baseElement;
 
@@ -1692,7 +1714,10 @@ abstract class FormalParameterElement
 ///
 /// Clients may not extend, implement, or mix-in this class.
 abstract class FormalParameterFragment
-    implements VariableFragment, Annotatable, LocalFragment {
+    implements
+        VariableFragment,
+        Annotatable, // ignore:deprecated_member_use_from_same_package
+        LocalFragment {
   @override
   FormalParameterElement get element;
 
@@ -1735,6 +1760,12 @@ abstract class Fragment {
   @Deprecated('Use children instead')
   List<Fragment> get children3;
 
+  /// The content of the documentation comment (including delimiters) for this
+  /// fragment.
+  ///
+  /// Returns `null` if the fragment doesn't have documentation.
+  String? get documentationComment;
+
   /// The element composed from this fragment and possibly other fragments.
   Element get element;
 
@@ -1749,6 +1780,11 @@ abstract class Fragment {
   /// This will be the fragment itself if it is a library fragment.
   LibraryFragment? get libraryFragment;
 
+  /// The metadata associated with the fragment.
+  ///
+  /// The list will be empty if the fragment does not have any metadata.
+  Metadata get metadata;
+
   /// The name of the fragment.
   ///
   /// Never empty.
@@ -2564,7 +2600,11 @@ abstract class LabelFragment implements Fragment {
 /// A library.
 ///
 /// Clients may not extend, implement or mix-in this class.
-abstract class LibraryElement implements Element, Annotatable {
+abstract class LibraryElement
+    implements
+        Element,
+        Annotatable // ignore:deprecated_member_use_from_same_package
+        {
   /// The classes defined in this library.
   ///
   /// There is no guarantee of the order in which the classes will be returned.
@@ -3045,7 +3085,11 @@ abstract class LocalFunctionFragment
 ///
 /// Clients may not extend, implement or mix-in this class.
 abstract class LocalVariableElement
-    implements VariableElement, LocalElement, Annotatable {
+    implements
+        VariableElement,
+        LocalElement,
+        Annotatable // ignore:deprecated_member_use_from_same_package
+        {
   @override
   LocalVariableElement get baseElement;
 
@@ -3523,7 +3567,11 @@ abstract class PropertyAccessorFragment implements ExecutableFragment {
 ///   [PropertyInducingElement].
 ///
 /// Clients may not extend, implement or mix-in this class.
-abstract class PropertyInducingElement implements VariableElement, Annotatable {
+abstract class PropertyInducingElement
+    implements
+        VariableElement,
+        Annotatable // ignore:deprecated_member_use_from_same_package
+        {
   @override
   PropertyInducingFragment get firstFragment;
 
@@ -3584,7 +3632,10 @@ abstract class PropertyInducingElement implements VariableElement, Annotatable {
 ///
 /// Clients may not extend, implement or mix-in this class.
 abstract class PropertyInducingFragment
-    implements VariableFragment, Annotatable {
+    implements
+        VariableFragment,
+        Annotatable // ignore:deprecated_member_use_from_same_package
+        {
   @override
   PropertyInducingElement get element;
 
@@ -3868,7 +3919,11 @@ abstract class TypeAliasFragment
 /// An element that defines a type.
 ///
 /// Clients may not extend, implement or mix-in this class.
-abstract class TypeDefiningElement implements Element, Annotatable {
+abstract class TypeDefiningElement
+    implements
+        Element,
+        Annotatable // ignore:deprecated_member_use_from_same_package
+        {
   // TODO(brianwilkerson): Evaluate to see whether this type is actually needed
   //  after converting clients to the new API.
 
@@ -3882,7 +3937,11 @@ abstract class TypeDefiningElement implements Element, Annotatable {
 /// The portion of a [TypeDefiningElement] contributed by a single declaration.
 ///
 /// Clients may not extend, implement or mix-in this class.
-abstract class TypeDefiningFragment implements Fragment, Annotatable {
+abstract class TypeDefiningFragment
+    implements
+        Fragment,
+        Annotatable // ignore:deprecated_member_use_from_same_package
+        {
   @override
   TypeDefiningElement get element;
 
@@ -3943,7 +4002,11 @@ abstract class TypeParameterFragment implements TypeDefiningFragment {
 /// An element that has type parameters, such as a class, typedef, or method.
 ///
 /// Clients may not extend, implement or mix-in this class.
-abstract class TypeParameterizedElement implements Element, Annotatable {
+abstract class TypeParameterizedElement
+    implements
+        Element,
+        Annotatable // ignore:deprecated_member_use_from_same_package
+        {
   @override
   TypeParameterizedFragment get firstFragment;
 
@@ -3982,7 +4045,11 @@ abstract class TypeParameterizedElement implements Element, Annotatable {
 /// declaration.
 ///
 /// Clients may not extend, implement or mix-in this class.
-abstract class TypeParameterizedFragment implements Fragment, Annotatable {
+abstract class TypeParameterizedFragment
+    implements
+        Fragment,
+        Annotatable // ignore:deprecated_member_use_from_same_package
+        {
   @override
   TypeParameterizedElement get element;