A bit of element model cleanup.

sdk/lib/_internal/compiler/implementation/elements/elements.dart

 // Copyright (c) 2012, 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 elements;
 
 
 import '../tree/tree.dart';
 import '../util/util.dart';
 import '../resolution/resolution.dart';
@@ skipping 267 matching lines @@
   /// This property is `false` if this element is an initializing formal.
   /// See [isInitializingFormal].
   bool get isParameter => kind == ElementKind.PARAMETER;
 
   /// `true` if this element is an initializing formal of constructor, that
   /// is a formal of the form `this.foo`.
   bool get isInitializingFormal => kind == ElementKind.INITIALIZING_FORMAL;
 
   bool get isStatement;
 
-  bool get isErroneous;
-  bool get isAmbiguous;
-  bool get isWarnOnUse;
+  /// `true` if this element represents a resolution error.
+  bool get isErroneous => kind == ElementKind.ERROR;
+
+  /// `true` if this element represents an ambiguous name.
+  ///
+  /// Ambiguous names occur when two imports/exports contain different entities
+  /// by the same name. If an ambiguous name is resolved an warning or error
+  /// is produced.
+  bool get isAmbiguous => kind == ElementKind.AMBIGUOUS;
+
+  /// `true` if this element represents an entity whose access should cause

[floitsch, 2014/07/21 08:55:34]

If our compiler is correct it always reports the warning. So maybe:

".. whose access causes one or more warnings."

[Johnni Winther, 2014/07/23 12:49:40]

Done.

+  /// one or more warnings.
+  bool get isWarnOnUse => kind == ElementKind.WARN_ON_USE;
 
   bool get isClosure;
 
   /// `true` if the element is a (static or instance) member of a class.
+  ///
   /// Members are constructors, methods and fields.
   bool get isClassMember;
 
   /// `true` if the element is a nonstatic member of a class.
+  ///
   /// Instance members are methods and fields but not constructors.
   bool get isInstanceMember;
 
   /// Returns true if this [Element] is a top level element.
   /// That is, if it is not defined within the scope of a class.
   ///
   /// This means whether the enclosing element is a compilation unit.
   /// With the exception of [ClosureClassElement] that is considered top level
   /// as all other classes.
   bool get isTopLevel;
@@ skipping 19 matching lines @@
 
   bool get impliesType;
 
   Token get position;
 
   CompilationUnitElement get compilationUnit;
   LibraryElement get library;
   LibraryElement get implementationLibrary;
   ClassElement get enclosingClass;
   Element get enclosingClassOrCompilationUnit;
-  Element get enclosingMember;
   Element get outermostEnclosingMemberOrTopLevel;
 
   /// The enclosing class that defines the type environment for this element.
   ClassElement get contextClass;
 
   FunctionElement asFunctionElement();
 
   /// Is [:true:] if this element has a corresponding patch.
   ///
   /// If [:true:] this element has a non-null [patch] field.
@@ skipping 411 matching lines @@
     TargetElement element = elements[body];
     // Labeled statements with no element on the body have no breaks.
     // A different target statement only happens if the body is itself
     // a break or continue for a different target. In that case, this
     // label is also always unused.
     return element == null || element.statement != body;
   }
 }
 
 /// An element representing an erroneous resolution.
+///
+/// An [ErroneousElement] is used instead of `null` to provide additional
+/// information about the error that caused the element to be unresolvable
+/// or otherwise invalid.
+///
+/// Accessing any field or calling any method defined on [ErroneousElement]
+/// except [isErroneous] will currently throw an exception. (This might
+/// change when we actually want more information on the erroneous element,
+/// e.g., the name of the element we were trying to resolve.)
+///
+/// Code that cannot not handle an [ErroneousElement] should use
+///     Element.isUnresolved(element)

[floitsch, 2014/07/21 08:55:34]

I would use backticks. `Element.isUnresolved(element)` to check for ... instead
of `element == null`.

Otherwise you have to add new lines around the code blocks.

[Johnni Winther, 2014/07/23 12:49:40]

Done.

+/// to check for unresolvable elements instead of
+///     element == null
 abstract class ErroneousElement extends Element implements ConstructorElement {
   MessageKind get messageKind;
   Map get messageArguments;
   String get message;
 }
 
-/// An [Element] whose usage should cause a warning.
+/// An [Element] whose usage should cause one or more warnings.
 abstract class WarnOnUseElement extends Element {
   /// The element whose usage cause a warning.
   Element get wrappedElement;
 
   /// Reports the attached warning and returns the wrapped element.
   /// [usageSpannable] is used to report messages on the reference of
   /// [wrappedElement].
   Element unwrap(DiagnosticListener listener, Spannable usageSpannable);
 }
 
-/// An element representing the ambiguous resolution of a name.
+/// An ambiguous element represents multiple elements accessible by the same
+/// name.
+///
+/// Ambiguous elements are created during handling of import/export scopes. If
+/// an ambiguous element is encountered during resolution a warning/error should

[floitsch, 2014/07/21 08:55:34]

same remark (about "should") as above.

[Johnni Winther, 2014/07/23 12:49:40]

Done.

+/// be reported.
 abstract class AmbiguousElement extends Element {
   MessageKind get messageKind;
   Map get messageArguments;
   Element get existingElement;
   Element get newElement;
 }
 
 // TODO(kasperl): This probably shouldn't be called an element. It's
 // just an interface shared by classes and libraries.
 abstract class ScopeContainerElement implements Element {
@@ skipping 153 matching lines @@
 }
 
 /// A top level, static or instance field, a formal parameter or local variable.
 abstract class VariableElement extends ExecutableElement {
   Expression get initializer;
 }
 
 /// An entity that defines a local entity (memory slot) in generated code.
 ///
 /// Parameters, local variables and local functions (can) define local entity
-/// and thus implement [Local] through [LocalElement]. For
-/// non-element locals, like `this` and boxes, specialized [Local] class are
-/// created.
+/// and thus implement [Local] through [LocalElement]. For non-element locals,
+/// like `this` and boxes, specialized [Local] classes are created.
 ///
 /// Type variables can introduce locals in factories and constructors
 /// but since one type variable can introduce different locals in different
 /// factories and constructors it is not itself a [Local] but instead
 /// a non-element [Local] is created through a specialized class.
 // TODO(johnniwinther): Should [Local] have `isAssignable` or `type`?
 abstract class Local extends Entity {
   /// The context in which this local is defined.
   ExecutableElement get executableContext;
 }
@@ skipping 542 matching lines @@
   bool get isDeclaredByField;
 
   /// Returns `true` if this member is abstract.
   bool get isAbstract;
 
   /// If abstract, [implementation] points to the overridden concrete member,
   /// if any. Otherwise [implementation] points to the member itself.
   Member get implementation;
 }