Introduce code to generate summaries from an element model.

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:
@@ skipping 39 matching lines @@
  * Annotation describing information which is not part of the public API to a
  * library; in other words, if this information (or any information it refers
  * to) changes, libraries outside this one are unaffected.
  *
  * TODO(paulberry): currently the summary format does not contain private
  * information.
  */
 const private = null;
 
 /**
+ * Annotation describing a class which can be the top level object in an
+ * encoded summary.
+ */
+const topLevel = null;
+
+/**
  * Information about a dependency that exists between one library and another
  * due to an "import" declaration.
  */
 class PrelinkedDependency {
   /**
    * The relative URI used to import one library from the other.
    */
   String uri;
 }
 
 /**
  * Pre-linked summary of a library.
  */
+@topLevel
 class PrelinkedLibrary {
   /**
    * The unlinked library summary.
    */
   UnlinkedLibrary unlinked;
 
   /**
    * The libraries that this library depends on (either via an explicit import
    * statement or via the implicit dependencies on `dart:core` and
    * `dart:async`).  The first element of this array is a pseudo-dependency
@@ skipping 24 matching lines @@
  * Information about the resolution of an [UnlinkedReference].
  */
 class PrelinkedReference {
   /**
    * Index into [UnlinkedLibrary.dependencies] indicating which imported library
    * declares the entity being referred to.
    */
   int dependency;
 
   /**
-   * The kind of the entity being referred to.
+   * The kind of the entity being referred to.  For the pseudo-type `dynamic`,
+   * the kind if [PrelinkedReferenceKind.classOrEnum].
    */
   PrelinkedReferenceKind kind;
 }
 
 /**
  * Enum used to indicate the kind of entity referred to by a
  * [PrelinkedReference].
  */
 enum PrelinkedReferenceKind {
   /**
@@ skipping 417 matching lines @@
    */
   String name;
 }
 
 /**
  * Unlinked summary information about a name referred to in one library that
  * might be defined in another.
  */
 class UnlinkedReference {
   /**
-   * Name of the entity being referred to.
+   * Name of the entity being referred to.  The empty string refers to the
+   * pseudo-type `dynamic`.
    */
   String name;
 
   /**
    * Prefix used to refer to the entity.  This is an index into
    * [UnlinkedLibrary.prefixes].
    */
   int prefix;
 }
 
@@ skipping 45 matching lines @@
   UnlinkedTypeRef bound;
 }
 
 /**
  * Unlinked summary information about a reference to a type.
  */
 class UnlinkedTypeRef {
   /**
    * Index into [UnlinkedLibrary.references] for the type being referred to, or
    * zero if this is a reference to a type parameter.
+   *
+   * Note that since zero is also a valid index into
+   * [UnlinkedLibrary.references], we cannot distinguish between references to
+   * type parameters and references to types by checking [reference] against
+   * zero.  To distinguish between references to type parameters and references
+   * to types, check whether [paramReference] is zero.
    */
   int reference;
 
   /**
-   * If this is a reference to a type parameter, one-based index into
-   * [UnlinkedClass.typeParameters] or [UnlinkedTypedef.typeParameters] for the
-   * parameter being referenced.  Otherwise zero.
+   * If this is a reference to a type parameter, one-based index into the list
+   * of [UnlinkedTypeParam]s currently in effect.  Indexing is done using De
+   * Bruijn index conventions; that is, innermost parameters come first, and
+   * if a class or method has multiple parameters, they are indexed from right
+   * to left.  So for instance, if the enclosing declaration is
    *
-   * If generic method syntax is enabled, this may also be a one-based index
-   * into [UnlinkedExecutable.typeParameters].  Note that this creates an
-   * ambiguity since it allows executables with type parameters to be nested
-   * inside other declarations with type parameters (which might themselves be
-   * executables).  The ambiguity is resolved by considering this to be a
-   * one-based index into a list that concatenates all type parameters that are
-   * in scope, listing the outermost type parameters first.
+   *     class C<T,U> {
+   *       m<V,W> {
+   *         ...
+   *       }
+   *     }
+   *
+   * Then [paramReference] values of 1, 2, 3, and 4 represent W, V, U, and T,
+   * respectively.  TODO(paulberry): test this.
+   *
+   * If the type being referred to is not a type parameter, [paramReference] is
+   * zero.
    */
   int paramReference;
 
   /**
    * If this is an instantiation of a generic type, the type arguments used to
    * instantiate it.  Trailing type arguments of type `dynamic` are omitted.
    */
   List<UnlinkedTypeRef> typeArguments;
 }
 
@@ skipping 48 matching lines @@
   /**
    * Indicates whether the variable is declared using the `final` keyword.
    */
   bool isFinal;
 
   /**
    * Indicates whether the variable is declared using the `const` keyword.
    */
   bool isConst;
 }