Provides block comment completion for Javadoc-style multi-line comments and single-line comment blocks for most officially supported languages.

MAJOR CHANGES IN 1.0 UPDATE (Please Read)

Search extensions for: baerkins.acf-snippets-vscode; VS Code Marketplace link; Auto Comment Blocks. You can easily insert multi-line comments. Just type /. + Enter and you’re good to go. Search extensions for: kevinkyang.auto-comment-blocks; VS Code Marketplace link.

• Visual Studio for Mac makes it straightforward to select, cut, copy, and paste sections of your code. Rectangular blocks of code can be highlighted and selected by using the Option + Drag command on the code block. The formatting within this block selection is retained when pasting the block.
• Extension for Visual Studio Code - VSCode plugin for extracting class names from HTML and generate CSS stylesheet for following work.
• The prefix # can be used to initiate a block comment: # This is a block heading # All adjacent comments will be considered part of the block. # # So long as you keep comments attached, they will remain part of the block.

A lot has changed in this update. Please open issues for any bugs you encounter.

Single-line Comment Blocks

You can now use single line comment blocks for languages with //, #, or ; style single line comments. Press Shift+Enter while on a commented line to insert a new commented line with the same level of indentation. See the Settings section for how to change the behavior so that Enter inserts a commented line while Shift+Enter breaks out of the comment block (this only works correctly for a subset of languages right now).

The Language Support section shows which languages are supported. See the Settings section for how to add single line comment support to languages that are not officially supported.

Multi-line Comment Blocks

This feature has not changed, but support has now been added for Less, Objective-C/C++, and Swift.

Usage

Javadoc-style comment blocks

Type /** to start a block comment, then hit the Enter key, and the extension will close the block. While inside the comment block, the extension will insert an asterisk at the start of every new line, and align the comment, respecting indentation.

QDoc-style (Qt) comment blocks

Use /*! in C/C++ files to start a QDoc comment block.

New: 'single-line' block comments

You can insert single line comment blocks for languages with //, #, or ; style single line comments. Press Shift+Enter while on a commented line to insert a new commented line with the same level of indentation. See the Settings section for issues and more options.

Language Support

Comment Style	Language Support
/** */	C, C++, C#, CSS, Go, Groovy, Java, Less, Objective C/C++, PHP, Sass, Rust, Swift
/*! */	C, C++
//, ///	C, C++, C#, F#, Go, Groovy, Java, JavaScript, Less, Objective C/C++, PHP, Rust, Sass, Swift, TypeScript
#	CoffeeScript, Dockerfile, Makefile, Perl, PowerShell, Python, R, Ruby, YAML
;	Clojure

Settings

Reload the extension after changing any settings.

• auto-comment-blocks.singleLineBlockOnEnter: If enabled, pressing Enter inserts a new commented line at the same indentation, and pressing Shift+Enter breaks the comment block.
  • Caution: This feature is buggy in many languages (see Issues section), but it seems to work fine for C, C++, Go, Less, PHP, Ruby, and Sass.
• auto-comment-blocks.disabledLanguages: Add languageIds here to disable any comment completion for that language.
• auto-comment-blocks.slashStyleBlocks: Add languageIds here to enable '//' and '///'-style single line comment blocks for that language.
• auto-comment-blocks.hashStyleBlocks: Add languageIds here to enable '#'-style single line comment blocks for that language.
• auto-comment-blocks.semicolonStyleBlocks: Add languageIds here to enable ';'-style single line comment blocks for that language.

Issues

• Single-line blocks using Enter: if you enable the singleLineBlockOnEnter setting, there are a few things to keep in mind:
  • It seems to work find for C, C++, Go, Less, PHP, Ruby, and Sass.
  • It doesn't work at all for Python, JavaScript, and TypeScript.
  • For every other language, if you press Tab immediately after breaking out of a comment block, it will insert a commented line, for some unknown reason.
• Sometimes multi-line completion/aseterisk insertion doesn't work. The reason is still unknown. It may go away if you reload your workspace.
• Currently, VS Code only allows extensions to overwrite, instead of modify, existing language configurations. This means that this extension may clash with another extension that overwrites the same language configurations, causing one or both not to work. In that case, uninstalling this extension is the only option for now.

Please create an issue in the repository if you find any bugs, or have questions or feature requests.

Release Notes

1.0.0

• Add multi-line comment support for Less, Objective-C/C++, and Swift.
• Add single-line comment blocks for most officially supported languages. See README for more information.

This document covers the various contribution points that are defined in the package.json extension manifest.

contributes.configuration

Contribute configuration keys that will be exposed to the user. The user will be able to set these configuration options either from User Settings or from the Workspace Settings.

When contributing configuration keys, a JSON schema describing these keys is actually contributed. This ensures the user gets great tooling support when authoring VS Code settings files.

You can read these values from your extension using vscode.workspace.getConfiguration('myExtension').

Example

contributes.configurationDefaults

Contribute default language specific editor configurations. This will override default editor configurations for the provided language.

The following example contributes default editor configurations for the markdown language:

Example

contributes.commands

Contribute an entry consisting of a title and a command to invoke to the Command Palette (kb(workbench.action.showCommands)).

Note: When a command is invoked (from a key binding or from the Command Palette), VS Code will emit an activationEvent onCommand:${command}.

Example

contributes.menus

Contribute a menu item for a command to the editor or Explorer. The menu item definition contains the command that should be invoked when selected and the condition under which the item should show. The latter is defined with the when clause which uses the key bindings when clause contexts. In addition to the mandatory command property, an alternative command can be defined using the alt-property. It will be shown and invoked when pressing kbstyle(Alt) while hovering over a menu item. Last, a group-property defines sorting and grouping of menu items. The navigation group is special as it will always be sorted to the top/beginning of a menu.

Currently extension writers can contribute to:

• The global Command Palette - commandPalette
• The Explorer context menu - explorer/context
• The editor context menu - editor/context
• The editor title menu bar - editor/title
• The editor title context menu - editor/title/context
• The debug callstack view context menu - debug/callstack/context
• The SCM title menu - scm/title
• SCM resource groups menus - scm/resourceGroup/context
• SCM resources menus - scm/resource/context
• The View title menu - view/title
• The View item menu - view/item/context

Note: When a command is invoked from a (context) menu, VS Code tries to infer the currently selected resource and passes that as a parameter when invoking the command. For instance, a menu item inside the Explorer is passed the URI of the selected resource and a menu item inside an editor is passed the URI of the document.

In addition to a title, commands can also define icons which VS Code will show in the editor title menu bar.

Example

Context specific visibility of Command Palette menu items

When registering commands in package.json, they will automatically be shown in the Command Palette (kb(workbench.action.showCommands)). To allow more control over command visibility, there is the commandPalette menu item. It allows you to define a when condition to control if a command should be visible in the Command Palette or not.

The snippet below makes the 'Hello World' command only visible in the Command Palette when something is selected in the editor:

Sorting of groups

Menu items can be sorted into groups. They are sorted in lexicographical order with the following defaults/rules.

The context menu of the editor has these default:

• navigation - The navigation group comes first in all cases.
• 1_modification - This group comes next and contains commands that modify your code.
• 9_cutcopypaste - The last default group with the basic editing commands.

You can add menu items to these groups or add new groups of menu items in between, below, or above. Only the editor context menu allows this grouping control.

Sorting inside groups

The order inside a group depends on the title or an order-attribute. The group-local order of a menu item is specified by appending @<number> to the group identifier as shown below:

contributes.keybindings

Contribute a key binding rule defining what command should be invoked when the user presses a key combination. See the Key Bindings topic where key bindings are explained in detail.

Contributing a key binding will cause the Default Keyboard Shortcuts to display your rule, and every UI representation of the command will now show the key binding you have added. And, of course, when the user presses the key combination the command will be invoked.

Note: Because VS Code runs on Windows, Mac and Linux, where modifiers differ, you can use 'key' to set the default key combination and overwrite it with a specific platform.

Note: When a command is invoked (from a key binding or from the Command Palette), VS Code will emit an activationEvent onCommand:${command}.

Example

Defining that kbstyle(Ctrl+F1) under Windows and Linux and kbstyle(Cmd+F1) under Mac trigger the 'extension.sayHello' command:

contributes.languages

Contribute the definition of a language. This will introduce a new language or enrich the knowledge VS Code has about a language.

In this context, a language is basically a string identifier that is associated to a file (See TextDocument.getLanguageId()).

VS Code uses three hints to determine the language a file will be associated with. Each 'hint' can be enriched independently:

1. the extension of the filename (extensions below)
2. the filename (filenames below)
3. the first line inside the file (firstLine below)

When a file is opened by the user, these three rules are applied and a language is determined. VS Code will then emit an activationEvent onLanguage:${language} (e.g. onLanguage:python for the example below)

The aliases property contains human readable names under which the language is known. The first item in this list will be picked as the language label (as rendered in the status bar on the right).

The configuration property specifies a path to the language configuration file. The path is relative to the extension folder, and is typically ./language-configuration.json. The file uses the JSON format and can contain the following properties:

• comments - Defines the comment symbols
• blockComment - The begin and end token used to mark a block comment. Used by the 'Toggle Block Comment' command.
• lineComment - The begin token used to mark a line comment. Used by the 'Add Line Comment' command.
• brackets - Defines the bracket symbols that influence the indentation of code between the brackets. Used by the editor to determine or correct the new indentation level when entering a new line.
• autoClosingPairs - Defines the open and close symbols for the auto-close functionality. When an open symbol is entered, the editor will insert the close symbol automatically. Auto closing pairs optionally take a notIn parameter to deactivate a pair inside strings or comments.
• surroundingPairs - Defines the open and close pairs used to surround a selected string.

If your language configuration file name is or ends with language-configuration.json, you will get validation and editing support in VS Code.

Example

language-configuration.json

contributes.debuggers

Contribute a debugger to VS Code. A debugger contribution has the following properties:

• type is a unique ID that is used to identify this debugger in a launch configuration.
• label is the user visible name of this debugger in the UI.
• program the path to the debug adapter that implements the VS Code debug protocol against the real debugger or runtime.
• runtime if the path to the debug adapter is not an executable but needs a runtime.
• configurationAttributes is the schema for launch configuration arguments specific to this debugger.
• initialConfigurations lists launch configurations that are used to populate an initial launch.json.
• configurationSnippets lists launch configurations that are available through IntelliSense when editing a launch.json.
• variables introduces substitution variables and binds them to commands implemented by the debugger extension.
• languages those languages for which the debug extension could be considered the 'default debugger'.
• adapterExecutableCommand the command ID where the debug adapters executable path and arguments are dynamically calculated. The command returns a structure with this format: json command: '<executable>', args: [ '<argument1>', '<argument2>', ... ] The attribute command must be a either an absolute path to an executable or a name of executable looked up via the PATH environment variable. The special value node will be mapped to VS Code's built-in node runtime without being looked up on the PATH.

Example

For a full walkthrough on how to integrate a debugger go to Debuggers.

contributes.breakpoints

Usually a debugger extension will also have a contributes.breakpoints entry where the extension lists the language file types for which setting breakpoints will be enabled.

contributes.grammars

Contribute a TextMate grammar to a language. You must provide the language this grammar applies to, the TextMate scopeName for the grammar and the file path.

Note: The file containing the grammar can be in JSON (filenames ending in .json) or in XML plist format (all other files).

Example

See Adding Language Colorization for instructions on using the yo code extension generator to quickly package TextMate .tmLanguage files as VS Code extensions.

contributes.themes

Contribute a TextMate theme to VS Code. You must specify a label, whether the theme is a dark theme or a light theme (such that the rest of VS Code changes to match your theme) and the path to the file (XML plist format).

Example

See Changing the Color Theme for instructions on using the yo code extension generator to quickly package TextMate .tmTheme files as VS Code extensions.

contributes.snippets

contributes.jsonValidation

Contribute a validation schema for a specific type of json file. The url value can be either a local path to a schema file included in the extension or a remote server URL such as a json schema store.

contributes.views

Contribute a view to VS Code. You must specify an identifier and name for the view. You can contribute to following locations:

• explorer: Explorer view in the Side Bar
• debug: Debug view in the Side Bar

Better Comments Vscode

When the user opens the view, VS Code will then emit an activationEvent onView:${viewId} (e.g. onView:nodeDependencies for the example below). You can also control the visibility of the view by providing the when context value.

Extension writers should register a provider programmatically to populate data in the view. Refer to examples here.

Mass Comment Vscode

contributes.problemMatchers

Contribute problem matcher patterns. These contributions work in both the output panel runner and in the terminal runner. Below is an example to contribute a problem matcher for the gcc compiler in an extension:

This problem matcher can now be used in a tasks.json file via a name reference $gcc. An example looks like this:

Also see: Defining a Problem Matcher

contributes.problemPatterns

Contributes named problem patterns that can be used in problem matchers (see above).

Next Steps

To learn more about VS Code extensibility model, try these topic:

• Extension Manifest File - VS Code package.json extension manifest file reference
• Activation Events - VS Code activation events reference