roslyn: Block comment / uncomment

Feature

Similar to other IDEs and languages, support for block comment / uncomment functionality would be useful. Some examples: https://www.jetbrains.com/help/ruby/commenting-and-uncommenting-blocks-of-code.html https://www.jetbrains.com/help/resharper/Coding_Assistance__Comment_Uncomment_Code.html https://www.jetbrains.com/help/idea/using-code-editor.html https://code.visualstudio.com/shortcuts/keyboard-shortcuts-windows.pdf

Proposal

In general, we are proposing a new ‘toggle block comment’ command. This command will be mapped to a single shortcut and will only act on block comments (not single line comments).

Command

The block commenting command will be a toggle based command. If the span selected contains a block comment it will be removed; otherwise, a block comment will be added. Details on the exact functionality will be explained below.

It will be accessible through a keyboard shortcut which by default would be mapped to Cntrl + Shift + /. This mapping is currently unused in a default visual studio installation.

Notes

1. Toggle behavior is almost universal across editors that have block comment functionality.
2. Cntrl + Shift + / happens to be the same command used by resharper for the same functionality. We considered alternatives such as Shift + Alt + A (the VS Code block comment command) but it was unfortunately already in use by Project.AddExistingItem

Functionality

The same command will both add and remove block comments depending on the context that the user has selected (highlighted).

Removing block comments

1. The selection contains a block comment section (plus whitespace). Matches current uncomment behavior.
2. The selection is contained entirely inside a block comment section. Matches current uncomment behavior. Other toggle block comment features usually do nothing.
3. The caret is inside a block comment section. Matches current uncomment behavior.
4. The caret is before the block comment open marker or after the block comment close marker on the same line with only whitespace.

Adding block comments

1. The selection contains no block comments.
2. The caret is not inside a block comment. A block comment will be added after the caret at the next whitespace. Similar to R#.
3. The selection contains all of a block comment plus other code. In this case, the comment will be extended to cover the newly selected pieces with multiple comments blocks. This is similar to how intellij functions.
4. The selection contains part of a block comment plus other code. When this case happens, we will add additional comments to cover the extra code being selected.
5. The caret is before (or after) the block comment open (or close) marker with only whitespace in between but on a different line.

Highlight

The comment section being added or removed will be selected once the command completes. Matches current behavior.

Changes to UI

No icon will be introduced for this command for the following reasons.

1. Introducing a toggle block comment icon would not make sense unless the current comment / uncomment icons were made into a single toggle button.
2. Adding two new icons to block comment or block uncomment would not work with a toggle command. The preference is for toggle over add / remove.
3. The existing icons and UI is rather unhelpful already.
4. We guess that these icons are rarely ever used over the keyboard shortcuts (TBD is that data available?)

Changes to existing comment / uncomment commands.

The existing comment / uncomment commands will be left as-is. We want to avoid breaking users’ existing workflows that they may be used to. This means that

1. The single line comment command can create a block comment when the selection is inside a single line.
2. The uncomment line comment command can uncomment block comments with similar functionality to block uncomment.

Prior work

Current VS Functionality

VS currently has separate comment and uncomment commands (comment: Cntrl+K,Cntrl+C, uncomment: Cntrl+K,Cntrl+U). These commands also have representation in the UI.

Commenting a selection will comment all lines that the selection spans with a single line comment. If the selection is inside one line, it will use a block comment on the selection.
Uncommenting a selection tries the following steps in order.

1. Uncomment a block comment span if the selected span exactly matches the block comment span.
2. Uncomment any single line comment (or multiple single line comments) on the selected span’s lines.
3. Uncomment any block comment that surrounds the selected span.

Resharper Functionality

Resharper has separate command toggles for dealing with single line comments and block comments. Cntrl+Alt+/ will comment and uncomment single line comments. Cntrl+Shift+/ will comment and uncomment block comments. If there is a selection, it will add a block comment around the selection. If the selection exactly matches a block comment, it will uncomment the selection. If the selection is within a block comment it will do nothing. If the caret is inside a block comment, it will uncomment the block.

Intellij

Block comments are toggled in intellij with Cntrl+Shift+/. It functions the same as resharper.

VS Code

Shift+Alt+A toggles block comments in VS code. This toggle looks at the lines of code to determine whether or not to comment or uncomment the block. If the first and last line of the selection contain block comment characters, it will uncomment them. Otherwise, it will add a comment (even inside an existing block).