Generate XML documentation comments for Visual Studio Code.
Deprecated Announcement
C# for Visual Studio Code (powered by OmniSharp) now officially supports the documentation comment from v1.23.8 (December 18th, 2020). You can use the official one by turning on Editor: Format On Type.
~~This extension will be deprecated in the future. Thanks to the users who have supported me so far.~~
2023/3/11 No features will be added, but only maintenance of the library will continue at the user's request.
Usage
Type "///", it auto-generates an XML documentation comment like this:
Configuration
The menu under File > Preferences (Code > Preferences on Mac) provides entries to configure user and workspace settings. You are provided with a list of Default Settings. Copy any setting that you want to change to the related settings.json file.
settings.json
{
// single: Comments are single-line comments that start with three slashes (///) (Default)
// delimited: Delimited comments that start with a slash and two stars (/**)
"docomment.syntax": "single",
// Press the Enter key to activate a command (Default: false)
"docomment.activateOnEnter": false,
// User-controllable options
"docomment.advanced": {
"cs": {
"namespace" : {
"attributes" : ["summary"]
},
"class" : {
"attributes" : ["summary", "typeparam"]
},
"interface" : {
"attributes" : ["summary", "typeparam"]
},
"struct" : {
"attributes" : ["summary"]
},
"enum" : {
"attributes" : ["summary"]
},
"delegate" : {
"attributes" : ["summary", "param", "typeparam", "returns"]
},
"field" : {
"attributes" : ["summary"]
},
"property" : {
"attributes" : ["summary", "value"]
},
"method" : {
"attributes" : ["summary", "param", "typeparam", "returns"]
},
"event" : {
"attributes" : ["summary"]
}
}
},
// Insert spaces when pressing Tab.
"editor.insertSpaces": true,
// The number of spaces a tab is equal to.
"editor.tabSize": 4
}
To enable publishing XML documentation:
project.csproj
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<DocumentationFile>bin\YourApi.XML</DocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
When DocumentationFile compiler option was specified, but one or more constructs did not have comments, it will produce CS1591 warning. You can optionally add a <NoWarn>$(NoWarn);1591</NoWarn> property to avoid these warnings.
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<DocumentationFile>bin\YourApi.XML</DocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
Installation
- Install Visual Studio Code 1.76.0 or higher
- Launch Code
- From the extension view
Ctrl-Shift-X (Windows, Linux) or Cmd-Shift-X (macOS)
- Search and Choose the extension
C# XML Documentation Comments
- Reload Visual Studio Code
Supported Languages
Contributing to the Code
Clone a copy of the repo:
git clone https://github.com/kasecato/vscode-docomment.git
Building the code
First, install the package dependencies:
npm install
Now you can compile the code:
npm run compile
After the initial compile, the source files will be watched and recompiled
when changes are saved.
Contributors
License
This extension is licensed under the MIT License.
