Consider not splitting last line of block comment (or make configurable via flag?)

[ian-h-chamberlain]

It was suggested I file a separate issue for this:

---

Just to propose one additional use case for /* */ comment (non-)formatting: it's possible to toggle a block comment with a single # using something like the following:

{
  /* <-- Toggling a # line comment at the beginning of this line toggles the whole block
    services.foo = {
      enable = true;
      bar = "baz";
    };
  # */
}

For this kind of case I think it would be valuable to avoid splitting the final # */ onto two lines (and maybe also the first line, but that's less important). Otherwise this "quick toggle" results in invalid syntax, e.g.

{
  # /*
    <-- Toggling a # line comment at the beginning of this line toggles the whole block
      services.foo = {
        enable = true;
        bar = "baz";
      };
    #
  */
}

I use this in my configs to quickly toggle on/off large sections of the config. I'm not sure how popular a practice it is in general, but it seems to be moderately common from a cursory search:
https://github.com/search?q=lang%3Anix+%2F%28%23+%5C*%5C%2F%7C%23+%5C%2F%5C*%29%2F&type=code

Originally posted by @ian-h-chamberlain in #179 (comment)

---

As pointed out by others, the use of /* */ comments like this reduces line diffs when toggling blocks, but also cannot be used with any nested /* */ comments, since Nix does not support comment nesting like this.

I also wanted to point out the RFC 1 66 specification about multiline comments, it seems to me slightly ambiguous whether this kind of format would be conformant or not:

• Both /*//** and */ start on a new line each, and are vertically aligned (i.e. have the same level of indentation).
  [...]
• Whitespace immediately after /*//** and whitespace before */ may not be preserved.
• Content after /*//** on the same line may get shifted the next line.

In particular, the first point seems like it would tend to prevent the # */ format I am referring to, but the last point's use of "may" leads me to believe it would be acceptable for a formatter to skip adding a newline after /* (and perhaps by extension the newline before */?). Maybe someone who is more familiar with the intent of the RFC could comment on this?

[piegamesde]

This is a really niche and obscure use case, and I've never seen it before. However, it reminds me of KDL which has /- comments to comment out entire syntax nodes. OpenSCAD also has something similar with the * modifier.

Like with #179, I'd prefer seeing this solved in the Nix language itself by adding dedicated syntax for this kind of comments. (Also, for a similar reason I dislike commenting out code with /*, as it usually does not compose with multiple levels of commented out code)

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/formatting-team-meeting-2024-11-26/56643/1

[ian-h-chamberlain]

Like with #179, I'd prefer seeing this solved in the Nix language itself by adding dedicated syntax for this kind of comments. (Also, for a similar reason I dislike commenting out code with /*, as it usually does not compose with multiple levels of commented out code)

That's fair, and I think a language feature to support commenting out an expression (or maybe an attribute definition, or both?) would be great! (similar feelings about nested multiline comments).

In lieu of a language change like that, this weird comment format is what I've found works as a quick + dirty way to toggle a block, so I just wanted to describe a use case / papercut I ran into using the formatter with the current Nix language. It is pretty niche, which is why I was thinking about a more general-purpose /**/-toggle kind of feature instead of specifically supporting this comment format, so it could maybe also work for things like #179.

In any case, thanks for taking a look/considering this! If nothing else, maybe this discussion will help inform some other formatter's implementation decisions.