### */ ###

[satyr]

$ coffee -e '### */ ###'

.:2
  /* */ */
        ^
SyntaxError: Unexpected token *

[michaelficarra]

Nice catch.

[TrevorBurnham]

But how should this be fixed? Generate a compiler error if a block comment contains */? Change each instance of */ to *//*? (What would then happen to /*/?) How can the user's intent best be preserved?

I'm guessing that if someone puts */ in a block comment, they'd like it to show up as */ in a documentation generator, e.g. Docco. Also, the * should be preserved because they might be using Markdown. So, my proposal is to replace */ with */ (where / is the HTML escape sequence for /). It's not a perfect solution, but it should cover most cases.

[michaelficarra]

I agree, Trevor. Using the escape sequence for an asterisk is also a solution. Any reasons to pick one over the other?

[AlyxRen]

the reason he suggested using the escape for '/' becaue the * may be used in Markdown evaluation.

[michaelficarra]

Well, that's a good enough reason for me.

Looks like we can just change line 433 of nodes.coffee to

code = '/*' + multident(@comment.replace(/\*\//g,'*/'), @tab) + '*/'

[michaelficarra]

Opened pull request #1053, fixing this issue.

[jashkenas]

I'm afraid that translating to HTML entities isn't an acceptable solution. This is CoffeeScript to JavaScript -- not CoffeeScript to JS-that-might-be-displayed-within-HTML. If */ is an illegal sequence within a JS block comment, and there's no way to escape the slash (being a comment, with purely visual value), then it should be an illegal sequence in CoffeeScript as well. Patched at SHA: 4b78790

[satyr]

FYI, Coco went ahead and fixed the syntax to /* */.
### ### was inadequate for several reasons:

• Interferes with line comment, complicating both syntaxes.
• Oddball as a hereX variant (all others take the form QQ -> QQQQQQ).
• Awkward when you want:
  ###*
  • JSDoc style comments
  • @constructor

• This bug.

[michaelficarra]

I wouldn't be against changing coffee's multiline comments to use /* */ syntax, but I'm probably alone.

[TrevorBurnham]

I'd be fine with that, too. Can't think of any reason to prefer ###, really.

[ozra]

Agreed. Heck - why not both!? AND I still like the proposition of converting */ to / - perhaps an optional modifier character after ### to mark the block for safe guarding?

###
Documentary stuff
* Below you'll find code for the magic things that has soon to work!
###

/*
thisFunctionWillBeBackSoon()
    doMagicThatsAlmostWorkingByNow()
*/

# Yeah! Everybody wins!


###!
commented out and safe guarded */ */ */

function whyPhpStinks($beVerbose) {
    return "It's the scopes and..." /* let's just leave it! */
}
    function someJSFunction(param /*, thisp*/) { doStuff(param) }
###