A bit of element model cleanup.

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

Index: sdk/lib/_internal/compiler/implementation/elements/elements.dart
diff --git a/sdk/lib/_internal/compiler/implementation/elements/elements.dart b/sdk/lib/_internal/compiler/implementation/elements/elements.dart
index 8246b93fe12afe8ae5c6f48ad7b0c1979c0112b0..04a9bb705a45dffbd5255fe4bb38e68fabc7292d 100644
--- a/sdk/lib/_internal/compiler/implementation/elements/elements.dart
+++ b/sdk/lib/_internal/compiler/implementation/elements/elements.dart
@@ -285,17 +285,29 @@ abstract class Element implements Entity {
 
   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;
 
@@ -335,7 +347,6 @@ abstract class Element implements Entity {
   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.
@@ -767,13 +778,27 @@ class Elements {
 }
 
 /// 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;
@@ -784,7 +809,12 @@ abstract class WarnOnUseElement extends Element {
   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;
@@ -958,9 +988,8 @@ abstract class VariableElement extends ExecutableElement {
 /// 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