Move element handles out of generated

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

 // Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 library analyzer.src.generated.element_handle;
 
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/type.dart';
 import 'package:analyzer/src/dart/element/element.dart';
 import 'package:analyzer/src/generated/constant.dart';
 import 'package:analyzer/src/generated/engine.dart';
 import 'package:analyzer/src/generated/java_engine.dart';
 import 'package:analyzer/src/generated/resolver.dart';
 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)
       : super(resynthesizer, location);
 
   @override
   List<PropertyAccessorElement> get accessors => actualElement.accessors;
 
   @override
   ClassElement get actualElement => super.actualElement as ClassElement;
@@ skipping 115 matching lines @@
   MethodElement lookUpMethod(String methodName, LibraryElement library) =>
       actualElement.lookUpMethod(methodName, library);
 
   @override
   PropertyAccessorElement lookUpSetter(
           String setterName, LibraryElement library) =>
       actualElement.lookUpSetter(setterName, library);
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   List<PropertyAccessorElement> get accessors => actualElement.accessors;
 
   @override
   CompilationUnitElement get actualElement =>
@@ skipping 47 matching lines @@
   }
 
   @override
   ClassElement getEnum(String enumName) => actualElement.getEnum(enumName);
 
   @override
   ClassElement getType(String className) => actualElement.getType(className);
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   ConstructorElement get actualElement =>
       super.actualElement as ConstructorElement;
 
   @override
@@ skipping 19 matching lines @@
 
   @override
   ConstructorElement get redirectedConstructor =>
       actualElement.redirectedConstructor;
 
   @override
   ConstructorDeclaration computeNode() => actualElement.computeNode();
 }
 
 /**
- * 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 {
   /**
    * The unique integer identifier of this element.
    */
   final int id = 0;
 
   /**
    * The [ElementResynthesizer] which will be used to resynthesize elements on
    * demand.
    */
   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) {
       _elementReference = _resynthesizer.getElement(_location);
     }
     return _elementReference;
   }
 
   @override
   AnalysisContext get context => _resynthesizer.context;
@@ skipping 87 matching lines @@
     actualElement.visitChildren(visitor);
   }
 }
 
 /**
  * Interface which allows an [Element] handle to be resynthesized based on an
  * [ElementLocation].  The concrete classes implementing element handles use
  * 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)
       : super(resynthesizer, location);
 
   @override
   ExecutableElement get actualElement =>
       super.actualElement as ExecutableElement;
 
   @override
@@ skipping 36 matching lines @@
   DartType get returnType => actualElement.returnType;
 
   @override
   FunctionType get type => actualElement.type;
 
   @override
   List<TypeParameterElement> get typeParameters => actualElement.typeParameters;
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   ExportElement get actualElement => super.actualElement as ExportElement;
 
   @override
   List<NamespaceCombinator> get combinators => actualElement.combinators;
 
   @override
   LibraryElement get exportedLibrary => actualElement.exportedLibrary;
 
   @override
   ElementKind get kind => ElementKind.EXPORT;
 
   @override
   String get uri => actualElement.uri;
 
   @override
   int get uriEnd => actualElement.uriEnd;
 
   @override
   int get uriOffset => actualElement.uriOffset;
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   FieldElement get actualElement => super.actualElement as FieldElement;
 
   @override
   ClassElement get enclosingElement => actualElement.enclosingElement;
 
   @override
   bool get isEnumConstant => actualElement.isEnumConstant;
 
   @override
   ElementKind get kind => ElementKind.FIELD;
 
   @override
   VariableDeclaration computeNode() => actualElement.computeNode();
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   FunctionElement get actualElement => super.actualElement as FunctionElement;
 
   @override
   bool get isEntryPoint => actualElement.isEntryPoint;
 
   @override
   ElementKind get kind => ElementKind.FUNCTION;
 
   @override
   SourceRange get visibleRange => actualElement.visibleRange;
 
   @override
   FunctionDeclaration computeNode() => actualElement.computeNode();
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   FunctionTypeAliasElement get actualElement =>
       super.actualElement as FunctionTypeAliasElement;
 
   @override
@@ skipping 13 matching lines @@
   FunctionType get type => actualElement.type;
 
   @override
   List<TypeParameterElement> get typeParameters => actualElement.typeParameters;
 
   @override
   FunctionTypeAlias computeNode() => actualElement.computeNode();
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   ImportElement get actualElement => super.actualElement as ImportElement;
 
   @override
   List<NamespaceCombinator> get combinators => actualElement.combinators;
@@ skipping 17 matching lines @@
   String get uri => actualElement.uri;
 
   @override
   int get uriEnd => actualElement.uriEnd;
 
   @override
   int get uriOffset => actualElement.uriOffset;
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   ExecutableElement get enclosingElement =>
       super.enclosingElement as ExecutableElement;
 
   @override
   ElementKind get kind => ElementKind.LABEL;
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   LibraryElement get actualElement => super.actualElement as LibraryElement;
 
   @override
   CompilationUnitElement get definingCompilationUnit =>
@@ skipping 67 matching lines @@
       actualElement.getImportsWithPrefix(prefixElement);
 
   @override
   ClassElement getType(String className) => actualElement.getType(className);
 
   @override
   bool isUpToDate(int timeStamp) => actualElement.isUpToDate(timeStamp);
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   LocalVariableElement get actualElement =>
       super.actualElement as LocalVariableElement;
 
   @override
   ElementKind get kind => ElementKind.LOCAL_VARIABLE;
 
   @override
   SourceRange get visibleRange => actualElement.visibleRange;
 
   @override
   VariableDeclaration computeNode() => actualElement.computeNode();
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   MethodElement get actualElement => super.actualElement as MethodElement;
 
   @override
   ClassElement get enclosingElement => super.enclosingElement as ClassElement;
 
   @override
   bool get isStatic => actualElement.isStatic;
 
   @override
   ElementKind get kind => ElementKind.METHOD;
 
   @override
   MethodDeclaration computeNode() => actualElement.computeNode();
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   ParameterElement get actualElement => super.actualElement as ParameterElement;
 
   @override
   String get defaultValueCode => actualElement.defaultValueCode;
@@ skipping 11 matching lines @@
   List<ParameterElement> get parameters => actualElement.parameters;
 
   @override
   List<TypeParameterElement> get typeParameters => actualElement.typeParameters;
 
   @override
   SourceRange get visibleRange => actualElement.visibleRange;
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   PrefixElement get actualElement => super.actualElement as PrefixElement;
 
   @override
   LibraryElement get enclosingElement =>
       super.enclosingElement as LibraryElement;
 
   @override
   List<LibraryElement> get importedLibraries => LibraryElement.EMPTY_LIST;
 
   @override
   ElementKind get kind => ElementKind.PREFIX;
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   PropertyAccessorElement get actualElement =>
       super.actualElement as PropertyAccessorElement;
 
   @override
@@ skipping 17 matching lines @@
     } else {
       return ElementKind.SETTER;
     }
   }
 
   @override
   PropertyInducingElement get variable => actualElement.variable;
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   PropertyInducingElement get actualElement =>
       super.actualElement as PropertyInducingElement;
 
   @override
   PropertyAccessorElement get getter => actualElement.getter;
 
   @override
   DartType get propagatedType => actualElement.propagatedType;
 
   @override
   PropertyAccessorElement get setter => actualElement.setter;
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   ElementKind get kind => ElementKind.TOP_LEVEL_VARIABLE;
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   TypeParameterElement get actualElement =>
       super.actualElement as TypeParameterElement;
 
   @override
   DartType get bound => actualElement.bound;
 
   @override
   ElementKind get kind => ElementKind.TYPE_PARAMETER;
 
   @override
   TypeParameterType get type => actualElement.type;
 }
 
 /**
- * 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)
       : super(resynthesizer, location);
 
   @override
   VariableElement get actualElement => super.actualElement as VariableElement;
 
   @override
   DartObject get constantValue => actualElement.constantValue;
@@ skipping 17 matching lines @@
   @override
   bool get isPotentiallyMutatedInScope =>
       actualElement.isPotentiallyMutatedInScope;
 
   @override
   bool get isStatic => actualElement.isStatic;
 
   @override
   DartType get type => actualElement.type;
 }
-
-/**
- * TODO(scheglov) invalid implementation
- */
-class WeakReference<T> {
-  final T value;
-  WeakReference(this.value);
-  T get() => value;
-}