Minor cleanup to analyzer summary IDL.

pkg/analyzer/tool/summary/idl.dart

 // Copyright (c) 2015, 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.
 
 /**
  * This file is an "idl" style description of the summary format.  It is not
  * executed directly; instead it is parsed and transformed into code that
  * implements the summary format.
  *
  * The code generation process introduces the following non-typical semantics:
- * - Fields of type List have a default value of the empty list.
- * - Fields of type int have a default value of zero.
- * - Fields of type String have a defauld value of ''.
+ * - Fields of type List are never null, and have a default value of the empty
+ *   list.
+ * - Fields of type int are never null, and have a default value of zero.
+ * - Fields of type String are never null, and have a default value of ''.
  *
  * Terminology used in this document:
  * - "Unlinked" refers to information that can be determined from reading the
  *   .dart file for the library itself (including all parts) and no other
  *   files.
  * - "Prelinked" refers to information that can be determined from reading the
  *   unlinked information for the library itself and the unlinked information
  *   for all direct imports (plus the transitive closure of exports reachable
  *   from those direct imports).
  * - "Linked" refers to information that can be determined only from reading
@@ skipping 85 matching lines @@
    * that reference is resolved.
    */
   List<PrelinkedReference> references;
 }
 
 /**
  * Information about the resolution of an [UnlinkedReference].
  */
 class PrelinkedReference {
   /**
-   * Index into [LibraryElement.dependencies] indicating which imported library
+   * Index into [UnlinkedLibrary.dependencies] indicating which imported library
    * declares the entity being referred to.
    */
   int dependency;
 
-  @Flag('CLASS', 0, 'Indicates that the thing being referred to is a class')
+  @Flag('CLASS', 0,
+      'Indicates that the thing being referred to is a class or enum')
   @Flag('TYPEDEF', 1, 'Indicates that the thing being referred to is a typedef')
   @Flag('OTHER', 2,
       'Indicates that the thing being referred to is a variable or executable')
   @Flag('UNRESOLVED', 3,
       'Indicates that the thing being referred to was not found')
   int flags;
 }
 
 /**
  * Unlinked summary information about a class declaration.
@@ skipping 10 matching lines @@
    */
   @informative
   int unit;
 
   /**
    * Type parameters of the class, if any.
    */
   List<UnlinkedTypeParam> typeParameters;
 
   /**
-   * Supertype of the class, or `null` if the class doesn't explicitly declare
-   * a supertype.
+   * Supertype of the class, or `null` if either (a) the class doesn't
+   * explicitly declare a supertype (and hence has supertype `Object`), or (b)
+   * the class *is* `Object` (and hence has no supertype).
    */
   UnlinkedTypeRef supertype;
 
   /**
    * Mixins appering in a `with` clause, if any.
    */
   List<UnlinkedTypeRef> mixins;
 
   /**
    * Interfaces appearing in an `implements` clause, if any.
@@ skipping 36 matching lines @@
 /**
  * Unlinked summary information about an enum declaration.
  */
 class UnlinkedEnum {
   /**
    * Name of the enum type.
    */
   String name;
 
   /**
-   * Values listed in the enum declaration.
+   * Values listed in the enum declaration, in declaration order.
    */
   List<UnlinkedEnumValue> values;
 
   /**
    * Index into [UnlinkedLibrary.units] indicating which compilation unit the
    * enum is declared in.
    */
   @informative
   int unit;
 }
@@ skipping 37 matching lines @@
 
   /**
    * Declared return type of the executable.  Absent if the return type is
    * `void`.  Note that when strong mode is enabled, the actual return type may
    * be different due to type inference.
    */
   UnlinkedTypeRef returnType;
 
   /**
    * Parameters of the executable, if any.  Note that getters have no
-   * parameters, and setters have a single parameter.
+   * parameters (hence this will be the empty list), and setters have a single
+   * parameter.
    */
   List<UnlinkedParam> parameters;
 
   @Flag('FUNCTION', 0,
       'Indicates that the declaration is for a function or method')
   @Flag('GETTER', 1, 'Indicates that the declaration is for a getter')
   @Flag('SETTER', 2, 'Indicates that the declaration is for a setter')
   @Flag('CONSTRUCTOR', 3, 'Indicates that the declaration is for a constructor')
   @Flag('ABSTRACT', 4, 'Set if the declaration lacks a function body')
   @Flag('STATIC', 8, 'Set if the declaration includes the `static` keyword')
   @Flag('CONST', 16,
       'Set if the declaration includes the `const` keyword (constructors only)')
   @Flag('FACTORY', 32,
       'Set if the declaration includes the `factory` keyword (constructors only)')
   int flags;
 }
 
 /**
  * Unlinked summary information about an export declaration.
  */
 class UnlinkedExport {
   /**
-   * Relative URI used to reference the exported library.
+   * URI used in the source code to reference the exported library.
    */
   String uri;
 
   /**
    * Combinators contained in this import declaration.
    */
   List<UnlinkedCombinator> combinators;
 }
 
 /**
  * Unlinked summary information about an import declaration.
  */
 class UnlinkedImport {
   /**
-   * Relative URI used to reference the imported library.
+   * URI used in the source code to reference the imported library.
    */
   String uri;
 
   /**
    * Offset of the "import" keyword.  Zero for implicit imports.
    *
    * Note that explicit imports may also have an offset of zero.  To
    * distinguish explicit from implicit imports, look for the presence of the
    * [IMPLICIT] flag.
    */
@@ skipping 256 matching lines @@
    * Declared type of the variable.  Note that when strong mode is enabled, the
    * actual type of the variable may be different due to type inference.
    */
   UnlinkedTypeRef type;
 
   @Flag('STATIC', 1, 'Set if the declaration includes the `static` keyword')
   @Flag('FINAL', 2, 'Set if the declaration includes the `final` keyword')
   @Flag('CONST', 4, 'Set if the declaration includes the `const` keyword')
   int flags;
 }