Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
ian-h-chamberlain opened this issue Jul 22, 2024 · 0 comments

Comments

@ian-h-chamberlain
Copy link

ian-h-chamberlain commented Jul 22, 2024

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Todo
Development

No branches or pull requests

1 participant