Multi-line / Block / Inline Comments

[lordkekz]

Related problem

As far as I can tell, Nushell supports line comments which are started with a # but has no syntax for multi-line comments. This has been discussed before in https://github.com/nushell/nushell/discussions/5734 and https://github.com/nushell/nushell/discussions/6470.

Describe the solution you'd like

I suggest adding support for inline and multi-line comments. I think the syntax used by Powershell is reasonable:

# This is a line comment

<#
This is a block comment
which consists of several lines
#>

$a = 10; <# This is an inline comment #> while ($a -ge 0) { echo $a; $a--; }

Describe alternatives you've considered

No response

Additional context and details

No response

[amtoine]

this sounds like a sensible thing to look into :yum:

[stellarpower]

I know some languages argue that multi-line comments aren't needed these days, due to better text editor/IDE support.

Personally, I'm a fan of them, it's nice being able to toggle them on and off quickly, and also, it makes it much quicker to insert snippets into my code - then I can copy and paste them into the shell really quickly if I forget how to use a module I've made.

Also, it's not like they have to span several lines. In my own code, I might insert one inbetween arguments of a function to add a hint of something:

def concatenateTables [leftTable <# FIXME: need a type annotation here, but what to put? #>, rightTable] {}

using the syntax suggested above.

Personally, I find languages that only support comments to the end of a line to be limiting, and this stops me annotating my code quite as well as I'd like, although is not the end of the world.

Also, one thing that's a real nuisance coming from C/C++, is that multi-line comments can't be nested. When you're really debugging or working on some experimental code, I find myself commenting things out, then commenting out further, etc. C especially I don't think had single-line comments in the beginning, so multi-line tend to be used by C programmers frequently on just single lines. It then makes it really hard to comment out a whole section of code (maybe a function I was editing that now doesn't compile, and I need to move onto something else). So I actually started using macros, or people #if 0 whole blocks.

So if this would be possible to parse, I think it's really useful to allow nesting to an arbitrary depth.

[cablehead]

Suggestion from Doru on discord:

### repeating could work, and it could be extended for matching an equally sized # at the end, allowing for "nested" comments
I feel like it has basically no precedent though, besides python multiline strings, I dunno if another language does something like that
######
Commented out
###
ignored "nesting"
###
Still comments
######
It's similar to raw nushell strings at least

CabalCrow also noted that /* */ could conflict with parsing globs

[IanManske]

Future note: any inline comment syntax we choose needs to be easily distinguishable from raw string syntax r#''# . (Or, we can change the raw string sytnax :stuck_out_tongue:.)

[fdncred]

I could live with

<#
blah 
  blah 
   blah
#>

[kubouch]

In my view, block comments fall into the category of “nice to have”, but their complexity and other downsides outweigh their benefits.

For example, nesting:

<#
foo
<# bar #>
#>

Or what if someone has #> characters in their comment? We might need to support escapes if we want to use block comments as doc comments, unless we disallow using block comments as doc comments. Or comment delimiters appearing outside of comments, e.g., let msg = "<# spam". These should be easy to handle by the Nushell parser (still requiring design work and being significantly more complex than the basic comments), but code editors would have to support it correctly as well, e.g., tree-sitter grammar for correct highlighting, or block (un)commenting with a shortcut. It could make life harder for tooling developers.

Apart from complexity, multi-line comments are not viewable out of context. Right now, if you see a line in a git diff that doesn't start with #, you know it's code. That would no longer be true with multi-line comments.

[fdncred]

I'm not a real fan of block comments myself. It's easy enough in most editors to select the lines you want commented and hit the keyboard shortcut to comment them all out.

[MovGP0]

Rust uses // and /* */, so maybe we should use that.

The # and <# #> sign has the advantage of beeing more intuitive for user coming from other shells, but # might be used for some language feature in a future version of Rust.

[fdncred]

I'm not a fan of // and /* */ since we don't support either of those today.

[lordkekz]

@MovGP0

but # might be used for some language feature in a future version of Rust.

That shouldn't prevent Nushell from using it differently, right? Or am I missing something?

[God-damnit-all]

Rust uses // and /* */, so maybe we should use that.

The # and <# #> sign has the advantage of beeing more intuitive for user coming from other shells, but # might be used for some language feature in a future version of Rust.

But nushell is already using # as comments, so why is this relevant?