Move element handles out of generated

pkg/analyzer/lib/src/dart/element/handle.dart

Index: pkg/analyzer/lib/src/dart/element/handle.dart
diff --git a/pkg/analyzer/lib/src/generated/element_handle.dart b/pkg/analyzer/lib/src/dart/element/handle.dart
similarity index 86%
copy from pkg/analyzer/lib/src/generated/element_handle.dart
copy to pkg/analyzer/lib/src/dart/element/handle.dart
index 9ed587fcc2a8ff627165343095d5a8f0e4642a17..dfecff2269b5d055c97bc1d606a84a90f762a525 100644
--- a/pkg/analyzer/lib/src/generated/element_handle.dart
+++ b/pkg/analyzer/lib/src/dart/element/handle.dart
@@ -16,13 +16,13 @@ import 'package:analyzer/src/generated/source.dart';
 import 'package:analyzer/src/generated/utilities_dart.dart';
 
 /**
- * Instances of the class `ClassElementHandle` implement a handle to a `ClassElement`.
+ * A handle to a [ClassElement].
  */
 class ClassElementHandle extends ElementHandle implements ClassElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   ClassElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -158,15 +158,14 @@ class ClassElementHandle extends ElementHandle implements ClassElement {
 }
 
 /**
- * Instances of the class `CompilationUnitElementHandle` implements a handle to a
- * [CompilationUnitElement].
+ * A handle to a [CompilationUnitElement].
  */
 class CompilationUnitElementHandle extends ElementHandle
     implements CompilationUnitElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   CompilationUnitElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -234,15 +233,14 @@ class CompilationUnitElementHandle extends ElementHandle
 }
 
 /**
- * Instances of the class `ConstructorElementHandle` implement a handle to a
- * `ConstructorElement`.
+ * A handle to a [ConstructorElement].
  */
 class ConstructorElementHandle extends ExecutableElementHandle
     implements ConstructorElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   ConstructorElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -282,8 +280,7 @@ class ConstructorElementHandle extends ExecutableElementHandle
 }
 
 /**
- * The abstract class `ElementHandle` implements the behavior common to objects that implement
- * a handle to an [Element].
+ * A handle to an [Element].
  */
 abstract class ElementHandle implements Element {
   /**
@@ -298,29 +295,27 @@ abstract class ElementHandle implements Element {
   final ElementResynthesizer _resynthesizer;
 
   /**
-   * The location of this element, used to reconstitute the element if it has been garbage
-   * collected.
+   * The location of this element, used to reconstitute the element if it has
+   * not yet been resynthesized.
    */
   final ElementLocation _location;
 
   /**
-   * A reference to the element being referenced by this handle, or `null` if the element has
-   * been garbage collected.
+   * A reference to the element being referenced by this handle, or `null` if
+   * the element has not yet been resynthesized.
    */
   Element _elementReference;
 
   /**
    * Initialize a newly created element handle to represent the element at the
-   * given [_location].  [_resynthesizer] will be used to resynthesize the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
    * element when needed.
    */
   ElementHandle(this._resynthesizer, this._location);
 
   /**
-   * Return the element being represented by this handle, reconstituting the element if the
-   * reference has been set to `null`.
-   *
-   * @return the element being represented by this handle
+   * Return the element being represented by this handle, reconstituting the
+   * element if the reference has been set to `null`.
    */
   Element get actualElement {
     if (_elementReference == null) {
@@ -428,23 +423,32 @@ abstract class ElementHandle implements Element {
  * this interface to retrieve the underlying elements when queried.
  */
 abstract class ElementResynthesizer {
+  /**
+   * The context that owns the element to be resynthesized.
+   */
   final AnalysisContext context;
 
+  /**
+   * Initialize a newly created resynthesizer to resynthesize elements in the
+   * given [context].
+   */
   ElementResynthesizer(this.context);
 
+  /**
+   * Return the element referenced by the given [location].
+   */
   Element getElement(ElementLocation location);
 }
 
 /**
- * The abstract class `ExecutableElementHandle` implements the behavior common to objects that
- * implement a handle to an [ExecutableElement].
+ * A handle to an [ExecutableElement].
  */
 abstract class ExecutableElementHandle extends ElementHandle
     implements ExecutableElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   ExecutableElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -501,14 +505,13 @@ abstract class ExecutableElementHandle extends ElementHandle
 }
 
 /**
- * Instances of the class `ExportElementHandle` implement a handle to an `ExportElement`
- * .
+ * A handle to an [ExportElement].
  */
 class ExportElementHandle extends ElementHandle implements ExportElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   ExportElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -537,14 +540,14 @@ class ExportElementHandle extends ElementHandle implements ExportElement {
 }
 
 /**
- * Instances of the class `FieldElementHandle` implement a handle to a `FieldElement`.
+ * A handle to a [FieldElement].
  */
 class FieldElementHandle extends PropertyInducingElementHandle
     implements FieldElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   FieldElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -567,15 +570,14 @@ class FieldElementHandle extends PropertyInducingElementHandle
 }
 
 /**
- * Instances of the class `FunctionElementHandle` implement a handle to a
- * `FunctionElement`.
+ * A handle to a [FunctionElement].
  */
 class FunctionElementHandle extends ExecutableElementHandle
     implements FunctionElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   FunctionElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -598,15 +600,14 @@ class FunctionElementHandle extends ExecutableElementHandle
 }
 
 /**
- * Instances of the class `FunctionTypeAliasElementHandle` implement a handle to a
- * `FunctionTypeAliasElement`.
+ * A handle to a [FunctionTypeAliasElement].
  */
 class FunctionTypeAliasElementHandle extends ElementHandle
     implements FunctionTypeAliasElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   FunctionTypeAliasElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -640,14 +641,13 @@ class FunctionTypeAliasElementHandle extends ElementHandle
 }
 
 /**
- * Instances of the class `ImportElementHandle` implement a handle to an `ImportElement`
- * .
+ * A handle to an [ImportElement].
  */
 class ImportElementHandle extends ElementHandle implements ImportElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   ImportElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -685,13 +685,13 @@ class ImportElementHandle extends ElementHandle implements ImportElement {
 }
 
 /**
- * Instances of the class `LabelElementHandle` implement a handle to a `LabelElement`.
+ * A handle to a [LabelElement].
  */
 class LabelElementHandle extends ElementHandle implements LabelElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   LabelElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -706,14 +706,13 @@ class LabelElementHandle extends ElementHandle implements LabelElement {
 }
 
 /**
- * Instances of the class `LibraryElementHandle` implement a handle to a
- * `LibraryElement`.
+ * A handle to a [LibraryElement].
  */
 class LibraryElementHandle extends ElementHandle implements LibraryElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   LibraryElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -801,15 +800,14 @@ class LibraryElementHandle extends ElementHandle implements LibraryElement {
 }
 
 /**
- * Instances of the class `LocalVariableElementHandle` implement a handle to a
- * `LocalVariableElement`.
+ * A handle to a [LocalVariableElement].
  */
 class LocalVariableElementHandle extends VariableElementHandle
     implements LocalVariableElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   LocalVariableElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -830,14 +828,14 @@ class LocalVariableElementHandle extends VariableElementHandle
 }
 
 /**
- * Instances of the class `MethodElementHandle` implement a handle to a `MethodElement`.
+ * A handle to a [MethodElement].
  */
 class MethodElementHandle extends ExecutableElementHandle
     implements MethodElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   MethodElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -860,16 +858,15 @@ class MethodElementHandle extends ExecutableElementHandle
 }
 
 /**
- * Instances of the class `ParameterElementHandle` implement a handle to a
- * `ParameterElement`.
+ * A handle to a [ParameterElement].
  */
 class ParameterElementHandle extends VariableElementHandle
     with ParameterElementMixin
     implements ParameterElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   ParameterElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -901,13 +898,13 @@ class ParameterElementHandle extends VariableElementHandle
 }
 
 /**
- * Instances of the class `PrefixElementHandle` implement a handle to a `PrefixElement`.
+ * A handle to a [PrefixElement].
  */
 class PrefixElementHandle extends ElementHandle implements PrefixElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   PrefixElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -928,15 +925,14 @@ class PrefixElementHandle extends ElementHandle implements PrefixElement {
 }
 
 /**
- * Instances of the class `PropertyAccessorElementHandle` implement a handle to a
- * `PropertyAccessorElement`.
+ * A handle to a [PropertyAccessorElement].
  */
 class PropertyAccessorElementHandle extends ExecutableElementHandle
     implements PropertyAccessorElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   PropertyAccessorElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -974,15 +970,14 @@ class PropertyAccessorElementHandle extends ExecutableElementHandle
 }
 
 /**
- * The abstract class `PropertyInducingElementHandle` implements the behavior common to
- * objects that implement a handle to an `PropertyInducingElement`.
+ * A handle to an [PropertyInducingElement].
  */
 abstract class PropertyInducingElementHandle extends VariableElementHandle
     implements PropertyInducingElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   PropertyInducingElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -1003,15 +998,14 @@ abstract class PropertyInducingElementHandle extends VariableElementHandle
 }
 
 /**
- * Instances of the class `TopLevelVariableElementHandle` implement a handle to a
- * `TopLevelVariableElement`.
+ * A handle to a [TopLevelVariableElement].
  */
 class TopLevelVariableElementHandle extends PropertyInducingElementHandle
     implements TopLevelVariableElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   TopLevelVariableElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -1022,15 +1016,14 @@ class TopLevelVariableElementHandle extends PropertyInducingElementHandle
 }
 
 /**
- * Instances of the class `TypeParameterElementHandle` implement a handle to a
- * [TypeParameterElement].
+ * A handle to a [TypeParameterElement].
  */
 class TypeParameterElementHandle extends ElementHandle
     implements TypeParameterElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   TypeParameterElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -1051,15 +1044,14 @@ class TypeParameterElementHandle extends ElementHandle
 }
 
 /**
- * The abstract class `VariableElementHandle` implements the behavior common to objects that
- * implement a handle to an `VariableElement`.
+ * A handle to an [VariableElement].
  */
 abstract class VariableElementHandle extends ElementHandle
     implements VariableElement {
   /**
-   * Initialize a newly created element handle to represent the given element.
-   *
-   * @param element the element being represented
+   * Initialize a newly created element handle to represent the element at the
+   * given [_location]. The [_resynthesizer] will be used to resynthesize the
+   * element when needed.
    */
   VariableElementHandle(
       ElementResynthesizer resynthesizer, ElementLocation location)
@@ -1097,12 +1089,3 @@ abstract class VariableElementHandle extends ElementHandle
   @override
   DartType get type => actualElement.type;
 }
-
-/**
- * TODO(scheglov) invalid implementation
- */
-class WeakReference<T> {
-  final T value;
-  WeakReference(this.value);
-  T get() => value;
-}