Single-line comments in output #2365

Closed
davidchambers opened this Issue Jun 1, 2012 · 25 comments

Comments

Projects
None yet
@davidchambers
Contributor

davidchambers commented Jun 1, 2012

doctest brings Python-like doctests to JavaScript (not to CoffeeScript, at this stage) and CoffeeScript. For example:

// > Math.product(3, 4, 5)
// 60
// > Math.product(2, "ten")
// NaN
// > Math.product(6)
// undefined
Math.product = function() {
  var idx = arguments.length
  if (idx > 1) {
    var product = arguments[0]
    while (--idx) product *= arguments[idx]
    return product
  }
}

For this reason I'd find it useful to have certain single-line CoffeeScript comments appear as single-line JavaScript comments in the compiled output. Perhaps something like…

## > double(6)
## 12
double = (n) -> 2 * n

could become…

var double;

// > double(6)
// 12
double = function(n) {
  return 2 * n;
};

Perhaps others would find this behaviour useful. Then again, perhaps not (my use case strikes me as an edge case).

@jussiry

This comment has been minimized.

Show comment
Hide comment
@jussiry

jussiry Jun 1, 2012

What's the reason for removing single line comments in compilation in the first place? You'd think that the normal case would be to minify JS files anyway, when performance is an issue.

jussiry commented Jun 1, 2012

What's the reason for removing single line comments in compilation in the first place? You'd think that the normal case would be to minify JS files anyway, when performance is an issue.

@jashkenas

This comment has been minimized.

Show comment
Hide comment
@jashkenas

jashkenas Jun 1, 2012

Owner

Check out several previous conversations about doctests / suggestions for CoffeeScript addition. To summarize: we don't want to do it because doctests encourage overly simplistic tests in comments. They're not great as documentation, and they're not great tests -- it's better to do both in earnest.

Owner

jashkenas commented Jun 1, 2012

Check out several previous conversations about doctests / suggestions for CoffeeScript addition. To summarize: we don't want to do it because doctests encourage overly simplistic tests in comments. They're not great as documentation, and they're not great tests -- it's better to do both in earnest.

@jashkenas jashkenas closed this Jun 1, 2012

@davidchambers

This comment has been minimized.

Show comment
Hide comment
@davidchambers

davidchambers Jun 1, 2012

Contributor

I didn't intend to start (another) discussion on the merits of doctests. I'm familiar with the previous discussions, and appreciate your stance on the matter, Jeremy. Discussing the pros and cons of allowing specific (or all) single-line comments to be output, on the other hand, may well be worthwhile.


Aside: I agree with you, Jeremy, that doctests are not a replacement for unit tests. Usage examples, though, are often very useful. Executable usage examples have the benefit of being testable: unit tests test the code; doctests test the documentation. The other benefit of doctests is their ability to test private functions. The internal sorter function in string-extensions.js is a good example of an internal function which benefits from being testable in isolation.

Contributor

davidchambers commented Jun 1, 2012

I didn't intend to start (another) discussion on the merits of doctests. I'm familiar with the previous discussions, and appreciate your stance on the matter, Jeremy. Discussing the pros and cons of allowing specific (or all) single-line comments to be output, on the other hand, may well be worthwhile.


Aside: I agree with you, Jeremy, that doctests are not a replacement for unit tests. Usage examples, though, are often very useful. Executable usage examples have the benefit of being testable: unit tests test the code; doctests test the documentation. The other benefit of doctests is their ability to test private functions. The internal sorter function in string-extensions.js is a good example of an internal function which benefits from being testable in isolation.

@jashkenas

This comment has been minimized.

Show comment
Hide comment
@jashkenas

jashkenas Jun 1, 2012

Owner

Usage examples, though, are often very useful.

... yep, but except for purely functional methods with simple inputs and outputs, the best usage examples aren't doctest-able.

As for discussions on the inclusion of single line comments in the output, there's a bunch of conversations and tickets about that as well. To summarize: We'd love to do it, but we can't figure out how to parse 'em in order to preserve comment behavior, even in theory.

Owner

jashkenas commented Jun 1, 2012

Usage examples, though, are often very useful.

... yep, but except for purely functional methods with simple inputs and outputs, the best usage examples aren't doctest-able.

As for discussions on the inclusion of single line comments in the output, there's a bunch of conversations and tickets about that as well. To summarize: We'd love to do it, but we can't figure out how to parse 'em in order to preserve comment behavior, even in theory.

@davidchambers

This comment has been minimized.

Show comment
Hide comment
@davidchambers

davidchambers Jun 1, 2012

Contributor

To summarize: We'd love to do it, but we can't figure out how to parse 'em in order to preserve comment behavior, even in theory.

Oh, that's interesting. Thanks for your feedback.

Contributor

davidchambers commented Jun 1, 2012

To summarize: We'd love to do it, but we can't figure out how to parse 'em in order to preserve comment behavior, even in theory.

Oh, that's interesting. Thanks for your feedback.

@michaelficarra

This comment has been minimized.

Show comment
Hide comment
@michaelficarra

michaelficarra Jun 2, 2012

Collaborator

@jashkenas: @Constellation has made some excellent progress adding comment support to Esprima. It's definitely worth a look. See Constellation/esprima@6c6a0f0 and http://code.google.com/p/esprima/issues/detail?id=197

Collaborator

michaelficarra commented Jun 2, 2012

@jashkenas: @Constellation has made some excellent progress adding comment support to Esprima. It's definitely worth a look. See Constellation/esprima@6c6a0f0 and http://code.google.com/p/esprima/issues/detail?id=197

@Constellation

This comment has been minimized.

Show comment
Hide comment
@Constellation

Constellation Jun 3, 2012

In estools/escodegen#10, escodegen now making comment attacher and generating code with comment.
For example, this is 2-space converted jquery-1.7.0.js with preserving comment https://gist.github.com/2757675 by esprima and escodegen.
It is still buggy (because, 0.0.4-dev), but when version 0.0.4 released, we can provide the comment attacher.

In estools/escodegen#10, escodegen now making comment attacher and generating code with comment.
For example, this is 2-space converted jquery-1.7.0.js with preserving comment https://gist.github.com/2757675 by esprima and escodegen.
It is still buggy (because, 0.0.4-dev), but when version 0.0.4 released, we can provide the comment attacher.

@satyr

This comment has been minimized.

Show comment
Hide comment
@satyr

satyr Jun 3, 2012

Collaborator

Sticking comments to the nearest tokens is easy. Propagating those to AST/compilation is the hard part.

a  \ # number
/    # operator
b    # number again

[IDENTIFIER a "number"] [MATH / "operator"] [IDENTIFIER b "number again"] [TERMINATOR \n]

Block
  Op / "operator"
    Value "a" "number"
    Value "b" "number again"

a  // number
/  // operator
b  // number again
;

Not impossible--just pretty cumbersome.

Collaborator

satyr commented Jun 3, 2012

Sticking comments to the nearest tokens is easy. Propagating those to AST/compilation is the hard part.

a  \ # number
/    # operator
b    # number again

[IDENTIFIER a "number"] [MATH / "operator"] [IDENTIFIER b "number again"] [TERMINATOR \n]

Block
  Op / "operator"
    Value "a" "number"
    Value "b" "number again"

a  // number
/  // operator
b  // number again
;

Not impossible--just pretty cumbersome.

@jashkenas

This comment has been minimized.

Show comment
Hide comment
@jashkenas

jashkenas Jun 4, 2012

Owner

Yeah, although I could imagine a first pass printing them in more "convenient" locations. I think you could start by walking down within the expression and collecting / marking all encountered comments...

Owner

jashkenas commented Jun 4, 2012

Yeah, although I could imagine a first pass printing them in more "convenient" locations. I think you could start by walking down within the expression and collecting / marking all encountered comments...

@tonyxiao

This comment has been minimized.

Show comment
Hide comment
@tonyxiao

tonyxiao Jun 16, 2012

Would it make things any easier to only support comments that take up an entire line first? For instance

     # this comment is outputted to javascript
 a  = 23 - 4 # this comment is not outputted to javascript

Would it make things any easier to only support comments that take up an entire line first? For instance

     # this comment is outputted to javascript
 a  = 23 - 4 # this comment is not outputted to javascript
@ProLoser

This comment has been minimized.

Show comment
Hide comment
@ProLoser

ProLoser Jul 10, 2012

+1

I was thinking the same exact thing as @tonyxiao and really would like that done (at least)

+1

I was thinking the same exact thing as @tonyxiao and really would like that done (at least)

@chzmnky

This comment has been minimized.

Show comment
Hide comment
@chzmnky

chzmnky Jul 16, 2012

Apologies if this is a naive suggestion, but could we just have the CS parser check for single-line block comments and convert them to single-line JS comments?

For example:
### Single-line comment ###
and:
a = 23 - 4 ### inline comment ###

would output:
// Single-line comment
and:
a = 23 - 4; // inline comment

rather than:
/* Single-line comment */
and:
Parse error on line 1: Unexpected 'HERECOMMENT'

Admittedly it feels hacky and overly verbose, but it would allow single-line comments to be passed through in a cleaner fashion than they currently appear and might get around the parsing issues already mentioned. It would also be consistent in that all forms of block comment are passed through to JS, while CS one-liners are not.

chzmnky commented Jul 16, 2012

Apologies if this is a naive suggestion, but could we just have the CS parser check for single-line block comments and convert them to single-line JS comments?

For example:
### Single-line comment ###
and:
a = 23 - 4 ### inline comment ###

would output:
// Single-line comment
and:
a = 23 - 4; // inline comment

rather than:
/* Single-line comment */
and:
Parse error on line 1: Unexpected 'HERECOMMENT'

Admittedly it feels hacky and overly verbose, but it would allow single-line comments to be passed through in a cleaner fashion than they currently appear and might get around the parsing issues already mentioned. It would also be consistent in that all forms of block comment are passed through to JS, while CS one-liners are not.

@michaelficarra

This comment has been minimized.

Show comment
Hide comment
@michaelficarra

michaelficarra Jul 16, 2012

Collaborator

@robinbolton: Not easily. The CoffeeScript compiler is not a line-oriented tool.

Collaborator

michaelficarra commented Jul 16, 2012

@robinbolton: Not easily. The CoffeeScript compiler is not a line-oriented tool.

@granteagon

This comment has been minimized.

Show comment
Hide comment
@granteagon

granteagon Dec 3, 2012

I think this should really be a command line option --with-comments, for example.

I don't care about doctests, but writing comments for docco or for people who don't like CS makes this an important feature to me. Docco can parse the block comments, but when I use it on larger files, having both types of comments yields a prettier result.

I realize these are fringe cases depending on your point of view, but if you want to write something in CS, then later for whatever reason you need to use JS - comments could be preserved. Having that capability would make CS an even more indispensable tool.

I think this should really be a command line option --with-comments, for example.

I don't care about doctests, but writing comments for docco or for people who don't like CS makes this an important feature to me. Docco can parse the block comments, but when I use it on larger files, having both types of comments yields a prettier result.

I realize these are fringe cases depending on your point of view, but if you want to write something in CS, then later for whatever reason you need to use JS - comments could be preserved. Having that capability would make CS an even more indispensable tool.

@zamtools

This comment has been minimized.

Show comment
Hide comment
@zamtools

zamtools Dec 3, 2012

I've seen some CSS compressors use a ! at the beginning of a comment to indicate that the comment should persist in the generated source.

In the case of coffeescript, this might look like:

#! this is a comment that must persist

# this comment will not persist

zamtools commented Dec 3, 2012

I've seen some CSS compressors use a ! at the beginning of a comment to indicate that the comment should persist in the generated source.

In the case of coffeescript, this might look like:

#! this is a comment that must persist

# this comment will not persist
@granteagon

This comment has been minimized.

Show comment
Hide comment
@granteagon

granteagon Dec 3, 2012

The exclamation point seems kind of weird since it means 'not' in javascript. Seems like it's saying, it's not a comment. Maybe something like #/ this would work better. I also considered ## just using 2 hash marks but there's probably some reason this is a dumb idea.

The exclamation point seems kind of weird since it means 'not' in javascript. Seems like it's saying, it's not a comment. Maybe something like #/ this would work better. I also considered ## just using 2 hash marks but there's probably some reason this is a dumb idea.

@zamtools

This comment has been minimized.

Show comment
Hide comment
@zamtools

zamtools Dec 3, 2012

I consider the exclamation point to mean it's important. But I see the possible confusion. However, I think the forward slash feels awkward and is fairly common in JS code so it could be easily confused as an errant character.

Double hashes would be elegant, but might be an issue because some people do weird commenting blocks like:

##### MAJOR SECTION

zamtools commented Dec 3, 2012

I consider the exclamation point to mean it's important. But I see the possible confusion. However, I think the forward slash feels awkward and is fairly common in JS code so it could be easily confused as an errant character.

Double hashes would be elegant, but might be an issue because some people do weird commenting blocks like:

##### MAJOR SECTION
@granteagon

This comment has been minimized.

Show comment
Hide comment
@granteagon

granteagon Dec 3, 2012

Totally, agree. I would like to see the double hash as well, I just don't know how the parser works so I don't know if using a regex to detect double hash not followed by another hash is possible or high performance enough.

Totally, agree. I would like to see the double hash as well, I just don't know how the parser works so I don't know if using a regex to detect double hash not followed by another hash is possible or high performance enough.

@kof

This comment has been minimized.

Show comment
Hide comment
@kof

kof Aug 31, 2013

Please add single line comments to the compiled code. Even if you support some limited syntax of it its fully acceptable. Just support some easy common cases, thats it!

I haven't found old discussions about it, so I just tell what I think why its so important:

I am at the point to think about to use cs. To ensure my code will not die if cs will die I need to be sure that generated javascript can be used instead. If all the comments gets dropped away, generated js is only half worth of its original, so I think without single line comments I am LOCKED to coffee script.

kof commented Aug 31, 2013

Please add single line comments to the compiled code. Even if you support some limited syntax of it its fully acceptable. Just support some easy common cases, thats it!

I haven't found old discussions about it, so I just tell what I think why its so important:

I am at the point to think about to use cs. To ensure my code will not die if cs will die I need to be sure that generated javascript can be used instead. If all the comments gets dropped away, generated js is only half worth of its original, so I think without single line comments I am LOCKED to coffee script.

@kof

This comment has been minimized.

Show comment
Hide comment
@kof

kof Aug 31, 2013

Also people who are not familiar with cs reading generated code without single line comments is much harder.

kof commented Aug 31, 2013

Also people who are not familiar with cs reading generated code without single line comments is much harder.

@softguy

This comment has been minimized.

Show comment
Hide comment
@softguy

softguy Sep 12, 2013

I have created a solution that can compile coffeescript to js with all comments kept. I am using a different approach and it took only an hour to make it work. Instead of digging into the details of AST and coffeescript, I pre-process the original src file comments into block comment and convert it back after coffeescript finished compiling.
Now the code can be found now at http://www.transppt.com and I will try to put it into github also. @davidchambers
@kof

softguy commented Sep 12, 2013

I have created a solution that can compile coffeescript to js with all comments kept. I am using a different approach and it took only an hour to make it work. Instead of digging into the details of AST and coffeescript, I pre-process the original src file comments into block comment and convert it back after coffeescript finished compiling.
Now the code can be found now at http://www.transppt.com and I will try to put it into github also. @davidchambers
@kof

@FichteFoll

This comment has been minimized.

Show comment
Hide comment
@FichteFoll

FichteFoll Sep 20, 2013

@softguy, nice idea. However, it can't import the debug module for me and thus throws an exception.

Also, would it be possible to forward build commands, like -b? And could you possibly add a file to %APPDATA%\npm on Windows when installed using npm install -g coffee-utils that runs your tool similar to coffee-script? Because that path is automatically added to PATH.

Btw, I need this for writing userscripts because the metadata is required to be written using line comments, not blocks.

Edit: Just found a solution using JavaScript literal blocks with backticks (// comment).

@softguy, nice idea. However, it can't import the debug module for me and thus throws an exception.

Also, would it be possible to forward build commands, like -b? And could you possibly add a file to %APPDATA%\npm on Windows when installed using npm install -g coffee-utils that runs your tool similar to coffee-script? Because that path is automatically added to PATH.

Btw, I need this for writing userscripts because the metadata is required to be written using line comments, not blocks.

Edit: Just found a solution using JavaScript literal blocks with backticks (// comment).

@flying-sheep

This comment has been minimized.

Show comment
Hide comment
@flying-sheep

flying-sheep Jan 26, 2016

the label says duplicate, but what’s the number of the open issue about this feature request?

the label says duplicate, but what’s the number of the open issue about this feature request?

@flying-sheep

This comment has been minimized.

Show comment
Hide comment
@flying-sheep

flying-sheep Jan 30, 2016

can this please be reopened? @jashkenas?

can this please be reopened? @jashkenas?

@flying-sheep flying-sheep referenced this issue in rainforestapp/decaf Jan 30, 2016

Open

Template strings #2

@ArtemGovorov ArtemGovorov referenced this issue in wallabyjs/public May 15, 2017

Closed

Advanced logging in CoffeeScript #1159

@GeoffreyBooth

This comment has been minimized.

Show comment
Hide comment
@GeoffreyBooth

GeoffreyBooth Aug 3, 2017

Collaborator

Implemented via #4572. Sorry it took a while.

Collaborator

GeoffreyBooth commented Aug 3, 2017

Implemented via #4572. Sorry it took a while.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment