Generate documentation for enumeration values.

pkg/analyzer/lib/src/summary/format.dart

Index: pkg/analyzer/lib/src/summary/format.dart
diff --git a/pkg/analyzer/lib/src/summary/format.dart b/pkg/analyzer/lib/src/summary/format.dart
index 0597fea34504ea8f5625de1e262382f192fbd487..e31d93423cc573554f17c2f225a1db21dfb2ab21 100644
--- a/pkg/analyzer/lib/src/summary/format.dart
+++ b/pkg/analyzer/lib/src/summary/format.dart
@@ -15,12 +15,35 @@ import 'flat_buffers.dart' as fb;
  * [LinkedReference].
  */
 enum ReferenceKind {
+  /**
+   * The entity is a class or enum.
+   */
   classOrEnum,
+
+  /**
+   * The entity is a typedef.
+   */
   typedef,
+
+  /**
+   * The entity is a top level function.
+   */
   topLevelFunction,
+
+  /**
+   * The entity is a top level getter or setter.
+   */
   topLevelPropertyAccessor,
+
+  /**
+   * The entity is a prefix.
+   */
   prefix,
-  unresolved,
+
+  /**
+   * The entity being referred to does not exist.
+   */
+  unresolved
 }
 
 class _ReferenceKindReader extends fb.Reader<ReferenceKind> {
@@ -42,44 +65,272 @@ class _ReferenceKindReader extends fb.Reader<ReferenceKind> {
  * context of a stack which is initially empty.
  */
 enum UnlinkedConstOperation {
+  /**
+   * Push the value of the n-th constructor argument (where n is obtained from
+   * [UnlinkedConst.ints]) onto the stack.
+   */
   pushArgument,
+
+  /**
+   * Push the next value from [UnlinkedConst.ints] (a 32-bit unsigned integer)
+   * onto the stack.
+   *
+   * Note that Dart supports integers larger than 32 bits; these are
+   * represented by composing 32 bit values using the [shiftOr] operation.
+   */
   pushInt,
+
+  /**
+   * Pop the top value off the stack, which should be an integer.  Multiply it
+   * by 2^32, "or" in the next value from [UnlinkedConst.ints] (which is
+   * interpreted as a 32-bit unsigned integer), and push the result back onto
+   * the stack.
+   */
   shiftOr,
+
+  /**
+   * Push the next value from [UnlinkedConst.doubles] (a double precision
+   * floating point value) onto the stack.
+   */
   pushDouble,
+
+  /**
+   * Push the constant `true` onto the stack.
+   */
   pushTrue,
+
+  /**
+   * Push the constant `false` onto the stack.
+   */
   pushFalse,
+
+  /**
+   * Push the next value from [UnlinkedConst.strings] onto the stack.
+   */
   pushString,
+
+  /**
+   * Pop the top n values from the stack (where n is obtained from
+   * [UnlinkedConst.ints]), convert them to strings (if they aren't already),
+   * concatenate them into a single string, and push it back onto the stack.
+   *
+   * This operation is used to represent constants whose value is a literal
+   * string containing string interpolations.
+   */
   concatenate,
+
+  /**
+   * Pop the top value from the stack which should be string, convert it to
+   * a symbol, and push it back onto the stack.
+   */
   makeSymbol,
+
+  /**
+   * Push the constant `null` onto the stack.
+   */
   pushNull,
+
+  /**
+   * Evaluate a (potentially qualified) identifier expression and push the
+   * resulting value onto the stack.  The identifier to be evaluated is
+   * obtained from [UnlinkedConst.references].
+   *
+   * This operation is used to represent the following kinds of constants
+   * (which are indistinguishable from an unresolved AST alone):
+   *
+   * - A qualified reference to a static constant variable (e.g. `C.v`, where
+   *   C is a class and `v` is a constant static variable in `C`).
+   * - An identifier expression referring to a constant variable.
+   * - A simple or qualified identifier denoting a class or type alias.
+   * - A simple or qualified identifier denoting a top-level function or a
+   *   static method.
+   */
   pushReference,
+
+  /**
+   * Pop the top `n` values from the stack (where `n` is obtained from
+   * [UnlinkedConst.ints]) into a list (filled from the end) and take the next
+   * `n` values from [UnlinkedConst.strings] and use the lists of names and
+   * values to create named arguments.  Then pop the top `m` values from the
+   * stack (where `m` is obtained from [UnlinkedConst.ints]) into a list (filled
+   * from the end) and use them as positional arguments.  Use the lists of
+   * positional and names arguments to invoke a constant constructor whose name
+   * is obtained from [UnlinkedConst.strings], and whose class is obtained from
+   * [UnlinkedConst.references], and push the resulting value back onto the
+   * stack.
+   *
+   * Note that for an invocation of the form `const a.b(...)` (where no type
+   * arguments are specified), it is impossible to tell from the unresolved AST
+   * alone whether `a` is a class name and `b` is a constructor name, or `a` is
+   * a prefix name and `b` is a class name.  In this case it is presumed that
+   * `a` is a prefix name and `b` is a class name.
+   *
+   * TODO(paulberry): figure out how to resolve this ambiguity in the
+   * "prelinked" part of the summary.
+   */
   invokeConstructor,
+
+  /**
+   * Pop the top n values from the stack (where n is obtained from
+   * [UnlinkedConst.ints]), place them in a [List], and push the result back
+   * onto the stack.  The type parameter for the [List] is obtained from
+   * [UnlinkedConst.references].
+   */
   makeList,
+
+  /**
+   * Pop the top 2*n values from the stack (where n is obtained from
+   * [UnlinkedConst.ints]), interpret them as key/value pairs, place them in a
+   * [Map], and push the result back onto the stack.  The two type parameters for
+   * the [Map] are obtained from [UnlinkedConst.references].
+   */
   makeMap,
+
+  /**
+   * Pop the top 2 values from the stack, pass them to the predefined Dart
+   * function `identical`, and push the result back onto the stack.
+   */
   identical,
+
+  /**
+   * Pop the top 2 values from the stack, evaluate `v1 == v2`, and push the
+   * result back onto the stack.
+   *
+   * This is also used to represent `v1 != v2`, by composition with [not].
+   */
   equal,
+
+  /**
+   * Pop the top value from the stack, compute its boolean negation, and push
+   * the result back onto the stack.
+   */
   not,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 && v2`, and push the
+   * result back onto the stack.
+   */
   and,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 || v2`, and push the
+   * result back onto the stack.
+   */
   or,
+
+  /**
+   * Pop the top value from the stack, compute its integer complement, and push
+   * the result back onto the stack.
+   */
   complement,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 ^ v2`, and push the
+   * result back onto the stack.
+   */
   bitXor,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 & v2`, and push the
+   * result back onto the stack.
+   */
   bitAnd,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 | v2`, and push the
+   * result back onto the stack.
+   */
   bitOr,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 >> v2`, and push the
+   * result back onto the stack.
+   */
   bitShiftRight,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 << v2`, and push the
+   * result back onto the stack.
+   */
   bitShiftLeft,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 + v2`, and push the
+   * result back onto the stack.
+   */
   add,
+
+  /**
+   * Pop the top value from the stack, compute its integer negation, and push
+   * the result back onto the stack.
+   */
   negate,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 - v2`, and push the
+   * result back onto the stack.
+   */
   subtract,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 * v2`, and push the
+   * result back onto the stack.
+   */
   multiply,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 / v2`, and push the
+   * result back onto the stack.
+   */
   divide,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 ~/ v2`, and push the
+   * result back onto the stack.
+   */
   floorDivide,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 > v2`, and push the
+   * result back onto the stack.
+   */
   greater,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 < v2`, and push the
+   * result back onto the stack.
+   */
   less,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 >= v2`, and push the
+   * result back onto the stack.
+   */
   greaterEqual,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 <= v2`, and push the
+   * result back onto the stack.
+   */
   lessEqual,
+
+  /**
+   * Pop the top 2 values from the stack, compute `v1 % v2`, and push the
+   * result back onto the stack.
+   */
   modulo,
+
+  /**
+   * Pop the top 3 values from the stack, compute `v1 ? v2 : v3`, and push the
+   * result back onto the stack.
+   */
   conditional,
-  length,
+
+  /**
+   * Pop the top value from the stack, evaluate `v.length`, and push the result
+   * back onto the stack.
+   */
+  length
 }
 
 class _UnlinkedConstOperationReader extends fb.Reader<UnlinkedConstOperation> {
@@ -99,10 +350,25 @@ class _UnlinkedConstOperationReader extends fb.Reader<UnlinkedConstOperation> {
  * Enum used to indicate the kind of an executable.
  */
 enum UnlinkedExecutableKind {
+  /**
+   * Executable is a function or method.
+   */
   functionOrMethod,
+
+  /**
+   * Executable is a getter.
+   */
   getter,
+
+  /**
+   * Executable is a setter.
+   */
   setter,
-  constructor,
+
+  /**
+   * Executable is a constructor.
+   */
+  constructor
 }
 
 class _UnlinkedExecutableKindReader extends fb.Reader<UnlinkedExecutableKind> {
@@ -122,9 +388,20 @@ class _UnlinkedExecutableKindReader extends fb.Reader<UnlinkedExecutableKind> {
  * Enum used to indicate the kind of a parameter.
  */
 enum UnlinkedParamKind {
+  /**
+   * Parameter is required.
+   */
   required,
+
+  /**
+   * Parameter is positional optional (enclosed in `[]`)
+   */
   positional,
-  named,
+
+  /**
+   * Parameter is named optional (enclosed in `{}`)
+   */
+  named
 }
 
 class _UnlinkedParamKindReader extends fb.Reader<UnlinkedParamKind> {