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

Shortcut for commenting code using /// doc comment markers (similar to "Add Line Comment") #1619

Closed
adriank opened this issue Apr 15, 2019 · 19 comments
Labels
in editor Relates to code editing or language features is enhancement
Milestone

Comments

@adriank
Copy link

adriank commented Apr 15, 2019

Hi,

Is there a shortcut for doc comments in VSCode? If not, how about adding it?

Thanks,
Adrian

@DanTup
Copy link
Member

DanTup commented Apr 15, 2019

Assuming you mean the hovers, there's a built-in keybinding (VS Code, not Dart Code) for Cmd+K, Cmd+I to show that. It also shows up in the Command Palette as "Show Hover".

Is that what you're after?

@DanTup DanTup added the awaiting info Requires more information from the customer to progress label Apr 15, 2019
@adriank
Copy link
Author

adriank commented Apr 15, 2019

I mean this kind of comments https://www.dartlang.org/guides/language/effective-dart/documentation#do-use--doc-comments-to-document-members-and-types

In VSCode we have cmd+/ for normal comment // comment, but I don't see shortcut to add doc comments /// doc comment.

@DanTup
Copy link
Member

DanTup commented Apr 15, 2019

Oh, I see. There's no shortcut for that. Could you explain why you'd use this? The reason for Cmd+/ is to allow you to "comment out" code, but I don't think it makes sense to comment code out with ///.

Are you writing code and then wanting to add it into a doc comment as an example or something?

(as an workaround, you could use "Add Cursor to Line Ends", then press "Home", then type an additional /, though I admit that's not very elegant :-))

@adriank
Copy link
Author

adriank commented Apr 15, 2019

When you annotate methods, classes etc with doc comments, the annotation appears as a tooltip in VSCode. As in link I shared in previous post:

/// Deletes the file at [path].
///
/// Throws an [IOError] if the file could not be found. Throws a
/// [PermissionError] if the file is present but could not be deleted.
void delete(String path) {
  ...
}

If you write delete anywhere in the code, a popup with this comment appears and a developer knows how to use the function.

@DanTup
Copy link
Member

DanTup commented Apr 16, 2019

@adriank Sorry, I didn't word the question very well. I understand the reason for using doc comments, but I wasn't sure why you would end up with existing code that you wanted to comment this way. Normally, you would write the comment by starting with /// and then every time you press <enter> it will automatically add that for the next line.

I'm interested in the workflow that results in you having text that doesn't start with /// that you want to add it to later, since presumably you wouldn't write the doc comments without the ///?

@adriank
Copy link
Author

adriank commented Apr 16, 2019 via email

@DanTup
Copy link
Member

DanTup commented Apr 16, 2019

Copy &paste a code example

Got it, thanks. The current method that uses // is done by VS Code (we tell it what the block and single line comment markers are) so this would need some custom work, but I don't think it should be too complicated.

@DanTup DanTup added in editor Relates to code editing or language features is enhancement and removed awaiting info Requires more information from the customer to progress labels Apr 16, 2019
@DanTup DanTup changed the title Shortcut for doc comments Shortcut for commenting code using /// doc comment markers (similar to "Add Line Comment") Apr 16, 2019
@DanTup DanTup modified the milestones: Backlog, On Deck Apr 16, 2019
@DanTup DanTup modified the milestones: On Deck, Backlog Jul 18, 2019
@Merrit
Copy link

Merrit commented Dec 13, 2020

I also run into instances where I have a regular // comment (often multiple lines) before say a function or class, and I just want to convert it into a doc comment ///.

It isn't a huge deal to add cursors and add an extra slash, but yeah at some point a shortcut or something to toggle it would be nice. (low priority 😃)

@leafney
Copy link

leafney commented Mar 16, 2021

This is exactly what I want.

@eseidel
Copy link

eseidel commented Jun 8, 2021

Vertical selection plus typing a single / is probably the fastest way.
https://code.visualstudio.com/docs/editor/codebasics#_multiple-selections-multicursor
I find columnar selection super handy with things like home/end or per-word movement to handle cases like this. Hope that helps.

@DanTup
Copy link
Member

DanTup commented Jun 14, 2021

I had a quick look at adding a version of Toggle Line Comment that did triple slashes (that you could keybind over the default one). It turned out to be a little annoying because we can't tell the difference between commented code and other comments (especially once the code has already been commented with double slashes), so it adds /// to the rotation of comment code out/in:

Jun-14-2021 16-07-56

It could be bound to a different key, but that means you'd have to keep track to two different shortcuts though, one for commenting code and one when you want to do this.

I'm not against including this (without a keybinding, allowing you to add your own) if it seems like it may be useful though.

@Merrit
Copy link

Merrit commented Jun 14, 2021

I do like this 3-state toggle idea, although I could see it possibly being annoying compared to a separate shortcut. Conflicted on that.

If there was a separate shortcut, it could be quite similar: Ctrl + / versus Ctrl + Shift + / ?

Not super sure myself. 🤔

@DanTup
Copy link
Member

DanTup commented Jun 15, 2021

VS Code has a lot of keybindings already (and many users create their own) so trying to find an unused one is hard (on macOS, the standard command is Cmd+/ but Shift+Cmd+/ already opens the help menu and appears it can't be overridden).

If the functionality shown above would be useful, I'm happy to ship it without a keybinding (it would not replace the standard functionality) and if you'd like to use it you can add your own keybinding:

  • Running the Open Keyboard Shortcuts (JSON) command from the palette
  • Pasting in (update key as required):
    {
    	"key": "cmd+/",
    	"command": "dart.toggleLineComment",
    	"when": "editorTextFocus && !editorReadonly && editorLangId == dart"
    }

@DanTup DanTup modified the milestones: Backlog, v3.24.0 Jun 15, 2021
@adriank
Copy link
Author

adriank commented Jun 15, 2021

@DanTup dart.toggleLineComment doesn't work for me. Do I need to configure something else so that it works?

@DanTup
Copy link
Member

DanTup commented Jun 15, 2021

@adriank I haven't shipped this, I was trying to gauge if there was enough interest to make it worth merging and shipping. Have you read the last few comments above and seen the GIF, does it seem useful in its current form (a three-state toggle, that you can bind to your own key, or override the existing keybinding - on the understanding it'll add an extra /// step when uncomment code)?

@adriank
Copy link
Author

adriank commented Jun 15, 2021

@DanTup the cmd+/ should stay without changes and there should be a new command that turns the triple-slash comment on/off. I have comments bound to cmd+3. cmd+2 is without binding. I would like the cmd+3 to stay as is and cmd+2 to add/remove triple slash. Others probably would much more like having double slash comments under cmd+/ and cmd+shift+/ for the triple.

Rotation between double/triple/no comment would be a terrible user experience. There is no use case for changing double slash comment to triple and the same is true the other way around. They exist in separate parts of code.

Thanks for your involvement in this issue. My work would be much more productive if this ends up in Dart-Code!

@DanTup
Copy link
Member

DanTup commented Jun 15, 2021

There is no use case for changing double slash comment to triple and the same is true the other way around

This was specifically requested above:

I also run into instances where I have a regular // comment (often multiple lines) before say a function or class, and I just want to convert it into a doc comment ///.

It's simple to change it to just do /// and no prefix though.

I don't plan to replace the built-in command, but this could ship as an additional command if it seems useful.

@Merrit
Copy link

Merrit commented Jun 15, 2021

Having thought about it some, I think having an optional binding to set myself for the doc-comment toggle would be quite good, with the default comment toggle remaining unchanged. 👍

@DanTup
Copy link
Member

DanTup commented Jun 15, 2021

Ok, if I understand correctly there's not much value in it being tristate so I'll change it to just a simple toggle that does /// instead of //. However I will make it "upgrade" double-slash to triple-slash if the whole selection already has double-slash (rather than making 5 slashes). I think this addresses both things discussed above, without introducing the awkward three-states.

It will be a new command and not have any keybinding - you'll have to add your own binding if you want.

@DanTup DanTup closed this as completed in 30ff301 Jun 15, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
in editor Relates to code editing or language features is enhancement
Projects
None yet
Development

No branches or pull requests

5 participants