Dart-code: Auto-insert `//` for additional non-dartdoc comment lines

[jamesderlin]

https://github.com/Dart-Code/Dart-Code/issues/147 requested automatically inserting /// when pressing Enter on a dartdoc comment line, but could we do the same for non-dartdoc comment lines? IMO we should just preserve whatever the current comment marker is.

I vaguely recall seeing some discussion about this before, but if it happened, I seem unable to find it now. Is it intentionally not done because there's some expectation that users might be annoyed if they write a comment, hit Enter, and then expect to write code? If that's a concern, is it possible to have an option, or maybe make, say, Enter/Shift+Enter do different things?

[DanTup]

I vaguely recall seeing some discussion about this before, but if it happened, I seem unable to find it now. Is it intentionally not done because there's some expectation that users might be annoyed if they write a comment, hit Enter, and then expect to write code?

I don't recall discussing this - in fact I'm surprised we handled it for /// and not //. I thought maybe it would be automatic based on the language config, but it doesn't seem to work.

Given we're already doing it for /// I think it makes sense to do for // too. If this seems to cause friction, I'm happy to patch in a setting for it later.

or maybe make, say, Enter/Shift+Enter do different things?

I don't believe this is possible. We don't handle the keypresses ourselves, we just declare the rules and VS Code handled the execution.

[DanTup]

Apparently I didn't test this properly, as this is now firing for triple-slash comments too. I've filed #3245 to look at it. If I can't fix it to handle both correctly, I may need to revert this.

[DanTup]

nm, all is good!

[justinStratis]

Thanks for a great extension.

Can an option be added for this, please?

This breaks my expectations of how the editor should work and, AFAIK, isn't consistent with other languages. IMO, /// or /* */ differ from // in the context of pressing Enter. With the former, I'm in the mode of writing documentation (or at least larger) comments. In contrast, with //, I'm usually writing a single-line comment or I've just commented out a block of code. In either case, automatically adding // is undesirable and unexpected.

If I should create a new issue for this, I can.

[DanTup]

With the former, I'm in the mode of writing documentation (or at least larger) comments. In contrast, with `//, I'm usually writing a single-line comment or I've just commented out a block of code.

That's fair. I'm a bit on the fence - the new behaviour surprised me a few times (because I'm used to it not happening), but a few times was helpful to.

Please do file a new issue, and I'll add a setting. Thanks!

[DanTup]

FYI - After using this for a little longer, I've found that I write a lot more single-line comments than I really thought, so I'm questioning having this on my default. When I add an option, I may default it back to off - so if you want it and see it stop working, look for a setting that controls it (it will be noted in the release notes).

[DanTup]

Here's what I've added for vNext - tripleSlash will be the default. Feedback welcome (in #3248)!

[jamesderlin]

Sounds good to me.

[jamesderlin]

Another possibility to consider: always automatically insert comment markers when breaking up comments (i.e., inserting a newline into the middle of an existing comment). I've noticed that the VS Code Python extension does that.

A downside is that I don't know how that should work with the option.

[DanTup]

Yes, I like that - and I think it's reasonable to have it enabled always (as long as you haven't set the setting to none).

I've added this line to the end of the setting because I also couldn't come up with a better way, but I'm open to changing it before it ships if someone has a better idea. Thanks!

So with the default (tripleSlash), it won't add // to the end of a comment, but it will when there is text after the caret. It'll try to do the right thing with spaces too - so if you press <enter> with a space after the caret it will avoid inserting an additional one after the slashes.