Flow generics in comments

[jamiebuilds]

Flow supports generic types using the comment syntax in a couple key locations:

/* @flow */

function identity/*::<T>*/(value /*: T */)/*: T */ {
  return value;
}

class Container/*::<T>*/ {
  method/*::<U>*/() {
    return true;
  }
}

let arr = [1, 2, 3];
let copy = arr.map(/*:: <T> */(item /*: T */) /*: T */ => item);

But the following roughly equivalent CoffeeScript code:

# @flow

identity = ###::<T>### (value ###: T ###) ###: T ### ->
  value

class Container ###::<T> ###
  method: ###::<U> ### () -> true
  
arr = [1, 2, 3];
copy = arr.map(###:: <T> ###(item ###: T ###) ###: T ### => item)

Which compiles to:

// @flow
var Container, arr, copy, identity, val;

identity = function(/*::<T>*/value/*: T */)/*: T */ {
  return value;
};

Container/*::<T> */ = class Container {
  method() {
    return true;
  }

};

arr = [1, 2, 3];

copy = arr.map((/*:: <T> */item/*: T */)/*: T */ => {
  return item;
});

If CoffeeScript put the comments in the correct location for Flow generics, it would cover the entire Flow grammar 1-to-1

  // @flow
  var Container, arr, copy, identity, val;

- identity = function(/*::<T>*/value/*: T */)/*: T */ {
+ identity = function/*::<T>*/(value/*: T */)/*: T */ {
    return value;
  };

- Container/*::<T> */ = class Container {
+ Container = class Container /*::<T> */ {
    method() {
      return true;
    }

  };

  arr = [1, 2, 3];

- copy = arr.map((/*:: <T> */item/*: T */)/*: T */ => {
+ copy = arr.map(/*:: <T> */(item/*: T */)/*: T */ => {
    return item;
  });

[GeoffreyBooth]

So in other words, you need the comment to stay on the correct side of the parenthesis as you’ve written it? That’s going to be hard . . . the parentheses don’t become nodes in their own right when the code gets tokenized, and comments are technically properties of nodes (with attributes like whether they should appear before or after the node). I solved this problem for the “between the function closing parenthesis and function opening brace” case by converting -> and => into full-fledged nodes, but I don’t think the same will be possible for parentheses.

Not saying it can’t be done, nor that I don’t want to fix it, just that it’s not a trivial ask. How much flexibility is there, if any, as to where the comments can appear?

[jamiebuilds]

Flow /*::include*/ comments are kind of a parser hack, when the Flow parser sees them it just throws out the comment start/end tokens. So for this code:

ab/*::cd*/ef

Flow parses:

abcdef

Because of that, the comments need to appear exactly where they would be within the comment.

function fn<T>(...) {
function fn/*::<T>*/(...) {

[GeoffreyBooth]

Because of that, the comments need to appear exactly where they would be within the comment.

You mean, the comments need to appear exactly where the type annotation would be if you were using the non-comments version of Flow syntax?

That at least is a much simpler rule to follow. Are there any other situations where Flow syntax is unachievable with the current comments implementation?

[phaux]

I wouldn't mind having dedicated flow syntax as part of CoffeeScript syntax. For example :: type ascription operator which compiles to correct flow comments

f :: <T>(T, T) => T
f = (a, b) => a + b

Would compile to

var f /*: <T>(T, T) => T */
f = (a, b) => a + b

[jamiebuilds]

You mean, the comments need to appear exactly where the type annotation would be if you were using the non-comments version of Flow syntax?

Yes

Are there any other situations where Flow syntax is unachievable with the current comments implementation?

The only other thing I can think of is type assertions/cast expressions:

arr = [1, 2, 3]
(arr ###: Array<number> ###)  # type assertion
other = (arr ###: any ###)    # type cast

These are compiled without parenthesis:

var arr, other;
arr = [1, 2, 3];
arr/*: Array<number> */ // type assertion
other = arr/*: any */   // type cast

But the parens are required because otherwise the non-comment syntax in Flow would be ambiguous (because of labels in JS)