You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Shortcut for commenting code using /// doc comment markers (similar to "Add Line Comment") #1619
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".
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 :-))
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.voiddelete(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.
@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 ///?
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.
changed the title [-]Shortcut for doc comments [/-][+]Shortcut for commenting code using /// doc comment markers (similar to "Add Line Comment")[/+]on Apr 16, 2019
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 😃)
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:
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.
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
@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)?
@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!
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.
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. 👍
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.
Activity
DanTup commentedon Apr 15, 2019
Assuming you mean the hovers, there's a built-in keybinding (VS Code, not Dart Code) for
Cmd+K,Cmd+Ito show that. It also shows up in the Command Palette as "Show Hover".Is that what you're after?
adriank commentedon 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 commentedon 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 commentedon 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:
If you write
deleteanywhere in the code, a popup with this comment appears and a developer knows how to use the function.DanTup commentedon 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 commentedon Apr 16, 2019
DanTup commentedon Apr 16, 2019
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.[-]Shortcut for doc comments [/-][+]Shortcut for commenting code using /// doc comment markers (similar to "Add Line Comment")[/+]2 remaining items
Merrit commentedon 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 commentedon Mar 16, 2021
This is exactly what I want.
eseidel commentedon 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 commentedon 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: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 commentedon 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+/versusCtrl+Shift+/?Not super sure myself. 🤔
DanTup commentedon 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+/butShift+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:
keyas required):adriank commentedon Jun 15, 2021
@DanTup dart.toggleLineComment doesn't work for me. Do I need to configure something else so that it works?
DanTup commentedon 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 commentedon 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 commentedon Jun 15, 2021
This was specifically requested above:
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 commentedon 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 commentedon 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.