alternative syntax for block comments

[zdenko]

This PR adds alternative syntax for the comment block: #* comment *#.
I've checked the previous proposals for something similar but couldn't find anything (@vendethiel do your magic).

#*
All new features require tests.
All but the most trivial bug fixes
should also have new or updated tests.
*#

compiles to:

/*
All new features require tests.
All but the most trivial bug fixes
should also have new or updated tests.
*/

Easier writing of Flow’s comment types syntax.

# @flow

#*::
type Obj = {
  num: number,
};
*#

fn = (str #*: string *#, obj #*: Obj *#) #*: string *# ->
  str + obj.num

Improved readability of multiple comment blocks.

#*
Comments starts here.
*#

foo = (a) ->
  a + 1
  #*
  More comments here.
  *#

foo 41

#*
Ends here.
*#

[vendethiel]

I've checked the previous proposals for something similar but couldn't find anything (@vendethiel do your magic).

#1050?

[GeoffreyBooth]

This PR would be a breaking change:

#*
#* Block comment
#*

If anyone wrote the above, after your PR all their code would be commented out.

[zdenko]

@GeoffreyBooth you're right about the breaking change.
I'm taking another shot by changing the regex a little bit.

This

#*
#* Block comment
#*

foo = (a) ->
  a + 1
  #*
  More comments here.
  *#

foo 41

###
Ends here.
###

compiles into

//*
//* Block comment
//*
var foo;

foo = function(a) {
  return a + 1;
};

/*
More comments here.
*/
foo(41);

/*
Ends here.
*/

[aminland]

How about we just support /* */ block comments to make everyone's life easier? On most fonts a single '#' takes the same visual space as '/*'.

It's guaranteed not to break anyone's code since /* throws a compiler error

[GeoffreyBooth]

I don’t think we want to have lots of alternatives for comments syntax. We certainly don’t want to introduce a breaking change to create something we don’t need.

I sympathize with the ugliness of block comments for Flow that is inspiring this effort, but I think there might be a better approach: a preprocessor, similar to https://github.com/billymoon/illiterate. Imagine you make a new command-line utility called flowcoffee, that works just like coffee to process .flowcoffee files:

flowcoffee --compile --output dist/ src/

The files output would all be JavaScript, not CoffeeScript. So within flowcoffee, the following would happen:

1. Find all .flowcoffee files to process, the same way coffee finds .coffee files.
2. Parse the files somehow to add ### delimiters around the Flow type annotations, and store this revised code in memory as strings.
3. Use the coffeescript module via its Node API to compile these strings into JavaScript strings.
4. Save the JavaScript strings as .js files, the same way coffee does.

So you could fork coffee to do this, or start with something simpler. If you exposed a Node API for this the same way coffeescript does, this flowcoffee module could become a drop-in replacement for coffeescript in wrappers like gulp-coffee and coffeeify etc. There would be more work to integrate this into third-party plugins than if we patched something into coffeescript itself, but the upside is that you could do whatever you wanted, including breaking changes, because using flowcoffee would inherently be opt-in. This is arguably how we should’ve implemented Literate CoffeeScript and/or JSX.

Instead of Flow syntax like this:

fn = (str ###: string ###, obj ###: Obj ###) ###: string ### ->
  str + obj.num

You could do something like this, for example:

fn = (str : string, obj : Obj) : string ->
  str + obj.num

In this proposal, we’re using the fact that “space-colon-space” currently doesn’t compile in CoffeeScript, and therefore it can be a cue that flowcoffee should insert ### before the colon and another ### after whatever word follows the colon but before the next non-alphanumeric character. This could be done via regex, without the need for sophisticated parsing. So in other words, flowcoffee would convert the second example into the first example, which would then get compiled by coffeescript into JavaScript. You would need to create similar rules and handling for :: and whatever other Flow syntax you want to recognize.