Add single-line comment syntax to CJSX [Fixes #40]

[ConradIrwin]

Before this change it was not possible to comment inside CJSX templates.

• How to do inline comments? #40
• Comments in cjsx coffee-react#13

After this change, you can use the syntax:

 {#this is a cjsx comment}

The syntax was designed to look like a CJSX_ESCAPE that contains a
comment, but as the resulting coffee-script would be illegal this is
special-cased by the parser to return nothing.

Please let me know if you have any feedback on coding style, or feature
implementation.

FWIW: I also considered trying to special case CJSX escapes that contain
nothing but comments, but that would have required at least one extra new-line
for each comment, and would have caused things like {} to become valid syntax,
which I'm not sure is a good thing to do.

{# this is an empty CJSX ESCAPE
}

[ConradIrwin]

@jsdf any feedback about this? re your comment at jsdf/coffee-react#13

[jsdf]

Yep sorry to keep you waiting, I started investigating supporting comments like those officially supported in JSX but got stuck on some other more general refactoring needed in the codebase, which has gotten to be a bit of a nightmare. To be honest though after looking into the way JSX now does it I'd rather just implement comments like this:

<div>
  {### this is a comment ###}
  {
    # this is also a comment, but you probably wouldn't use this style
  }
  <MyComponent
    someProp="a" # comments in props are fine
    ###
    also comments like this
    are another option
    ###
    someOtherProp="b"
  />
</div>

This reflects the behaviour supported in JSX, and is logically consistent with the way comments usually work in the language.

Thus the # single hash comments inside a {code block} would not be supported. However you could still use a single line {### herecomment ###}, which doesn't work currently due to a bug but could be fixed.

[ConradIrwin]

Cool. I'll have a go at that syntax.

Unfortunately ### comments in coffee-script are much more limited than /* */ in javascript because they have to end at the end of the line, so we'll need to special case them in the same way to support this.

<div>{### comment ###}</div>

I'm not sure whether we need special cases for

{
# foo
} 

style; but I think we will (because CJSX expects {} to return a value, but comments aren't values).

[jsdf]

Oh you're totally right about the herecomment thing. I wasn't fully aware of that (though I vaguely remember running into it in the past).

In CJSX though, they get wrapped in parens which is compiled by coffeescript as the comment wrapped an anonymous function(?!) so you get this weird output:

React.createElement('div', (### comment ###))

becomes

React.createElement('div', ((function() {

  /* comment */
})()));

which looks pretty dumb, though if you're using UglifyJS with dead code elimination then it will become

React.createElement("div",void 0)

Still, we can probably do better by special casing it.

[jsdf]

We could introduce a different type of parse tree node CJSX_HERECOMMENT for comments appearing as children of CJSX_ATTRIBUTES or CJSX_ESC which could be output as escaped JS like

`/* comment */`

[jsdf]

Nevermind, coffeescript treats escaped JS as an expression so this won't work :/

[ConradIrwin]

For the attributes ones we can probably just output coffeescript comments, because the newlines will happily line up.

The hard one is the comment-only CJSX_ESCAPE.

[jsdf]

Ugh coffeescript block comments are terrible. I didn't actually realise how it treats block comments as a statement rather than being equivalent to JS block comments (which aren't statements, just ignored text). Maybe your original approach is best.

[ConradIrwin]

The thing I like most about the original request is that the comments look the nicest.

That said, I'd be keen to fix the comment-only CJSX_ESCAPE too (again probably by just not passing the comment through), though that doesn't have to be done at the same time.

[jsdf]

Okay I'm happy to merge this then, and I'll deal with the other cases seperately