First cut at idl changes

pkg/analyzer/lib/src/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
  * contains abstract classes which declare the interface for reading data from
  * summaries.  It is parsed and transformed into code that implements the
  * summary format.
  *
@@ skipping 338 matching lines @@
   int get length;
 
   /**
    * Offset of the element code relative to the beginning of the file.
    */
   @Id(0)
   int get offset;
 }
 
 /**
- * Summary information about a reference to a an entity such as a type, top
- * level executable, or executable within a class.
+ * Summary information about a reference to an entity such as a type, top level
+ * executable, or executable within a class.
  */
 abstract class EntityRef extends base.SummaryClass {
   /**
    * If this is a reference to a function type implicitly defined by a
    * function-typed parameter, a list of zero-based indices indicating the path
    * from the entity referred to by [reference] to the appropriate type
    * parameter.  Otherwise the empty list.
    *
    * If there are N indices in this list, then the entity being referred to is
    * the function type implicitly defined by a function-typed parameter of a
@@ skipping 70 matching lines @@
    */
   @Id(5)
   EntityRef get syntheticReturnType;
 
   /**
    * If this is an instantiation of a generic type or generic executable, the
    * type arguments used to instantiate it (if any).
    */
   @Id(1)
   List<EntityRef> get typeArguments;
+
+  /**
+   * If this is a function type, the type parameters defined for the function
+   * type (if any).
+   */
+  @Id(7)
+  List<UnlinkedTypeParam> get typeParameters;
 }
 
 /**
  * Enum used to indicate the kind of a name in index.
  */
 enum IndexNameKind {
   /**
    * A top-level element.
    */
   topLevel,
@@ skipping 2169 matching lines @@
   @Id(15)
   bool get isExplicitlyCovariant;
 
   /**
    * Indicates whether the parameter is declared using the `final` keyword.
    */
   @Id(16)
   bool get isFinal;
 
   /**
-   * Indicates whether this is a function-typed parameter.
+   * Indicates whether this is a function-typed parameter. A parameter is
+   * function-typed if the declaration of the parameter has explicit formal
+   * parameters
+   * ```
+   * int functionTyped(int p)
+   * ```
+   * but is not function-typed if it does not, even if the type of the parameter
+   * is a function type.
    */
   @Id(5)
   bool get isFunctionTyped;
 
   /**
    * Indicates whether this is an initializing formal parameter (i.e. it is
    * declared using `this.` syntax).
    */
   @Id(6)
   bool get isInitializingFormal;
@@ skipping 209 matching lines @@
 
   /**
    * Documentation comment for the typedef, or `null` if there is no
    * documentation comment.
    */
   @informative
   @Id(6)
   UnlinkedDocumentationComment get documentationComment;
 
   /**
+   * Indicates whether this is a generic function type. Generic function types
+   * do not have [parameters], but encode the function type being defined as the
+   * [returnType].
+   */
+  @Id(8)
+  bool get isGenericFunctionType;

[Paul Berry, 2017/02/28 17:06:49]

Question: How do you intend to represent a new-style typedef that does not
denote a generic function type, e.g.

typedef F = int Function(bool);

Would this flag be `true` or `false` in this case?

My two cents: I think the flag should be `true` in this case, since it will make
the code that generates summaries more uniform (any use of the form X
Function(Y, Z, ...) gets encoded in the same way, regardless of whether it has
type parameters and regardless of whether it appears in a typedef).

Assuming that's the case, I think we should rename this flag to something like
"isNewStyleTypedef" to avoid confusion.  (Otherwise, someone might assume that
this flag will be `true` only when the function type in question is truly
generic).

[Brian Wilkerson, 2017/02/28 17:19:57]

That question reveals a terminology issue. The name "generic function type" is
the only name I know to give to the new syntax that uses "Function" in place of
a function name (and requires types but not names for parameters). As I've been
using it, it does *not* mean, a function type that actually has type parameters,
it means a function type that could have type parameters because of being
expressed using this new syntax.

Hence, the example you gave is, in my understanding, still a generic function
type, so the flag would be true.
I'm fine with renaming this if there's a better name, but I won't use "NewStyle"
because if we later decide to support another style of typedef (and I've seen at
least two being discussed) they will be the "new" styles and I don't want to end
up with names like "NewerStyle" and "NewerThanNewStyle" :-)

In the absence of a better name, how about better documentation?

[Paul Berry, 2017/02/28 17:38:57]

Documentation is good, but it's even nicer when the variable name itself doesn't
suggest something counter to reality.  So let's not give up quite yet :)

I don't have a better name for the syntactic construct in question (perhaps we
should ask Leaf and/or the language team to come up with one), but I think we
could still come up with a name for this variable that makes the intention
clearer.

For example how about "usesGenericFunctionTypeSyntax"?  Or
"inGenericFunctionTypeForm"?

Alternatively, we could make this an enum called "style", and then the possible
values could be "cStyle" and "genericFunctionTypeStyle".  (Enums default to the
zeroth possible value, so this would still have the backwards compatibility
behavior we need).

I don't mind if you want to take one of those suggestions and wordsmith it
further to make it clearer; I just want to avoid having a variable name that
seems pretty clearly to mean something it doesn't.

+
+  /**
    * Name of the typedef.
    */
   @Id(0)
   String get name;
 
   /**
    * Offset of the typedef name relative to the beginning of the file.
    */
   @informative
   @Id(1)
   int get nameOffset;
 
   /**
    * Parameters of the executable, if any.
    */
   @Id(3)
   List<UnlinkedParam> get parameters;
 
   /**
    * Return type of the typedef.

[Paul Berry, 2017/02/28 17:06:49]

To reduce confusion, let's change this comment to something like:

If [isGenericFunctionType] is `false` return type of the typedef.  If
[isGenericFunctionType] is `true`, the function type being defined.

[Brian Wilkerson, 2017/02/28 17:19:57]

Good idea; will do.

    */
   @Id(2)
   EntityRef get returnType;
 
   /**
    * Type parameters of the typedef, if any.
    */
   @Id(5)
   List<UnlinkedTypeParam> get typeParameters;
 }
@@ skipping 294 matching lines @@
   @Id(11)
   int get visibleLength;
 
   /**
    * If a local variable, the beginning of the visible range; zero otherwise.
    */
   @informative
   @Id(12)
   int get visibleOffset;
 }