kasecato / vscode-docomment

Generate XML documentation comments for Visual Studio Code

XML Documentation Comments Support for Visual Studio Code

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

1. Install Visual Studio Code 1.76.0 or higher
2. Launch Code
3. From the extension view Ctrl-Shift-X (Windows, Linux) or Cmd-Shift-X (macOS)
4. Search and Choose the extension C# XML Documentation Comments
5. Reload Visual Studio Code

Supported Languages

• C#
• Blazor

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

• @kasecato
• @ivanz
• @PJB3005
• @Acid147
• @doggy8088

License

This extension is licensed under the MIT License.

vscode-docomment's Issues

Extra /// being added when saving file

Running VSCode on Mac. When I save (using either hotkey or file > save) and my cursor is at the end of a comment line the next line is commented out with an extra /// when the save is complete. This happens when the next line is either another comment or code.

For example:
(Note: cursor after 'world')

/// <summary>
/// Writes hello world|
/// </summary>
public void WriteHello(){}

Save
(Note: cursor moves to next line after new ///)

/// <summary>
/// Writes hello world
/// |/// </summary>
public void WriteHello(){}

For example:
(Note: cursor after '')

/// <summary>
/// Writes hello world
/// </summary>|
public void WriteHello(){}

Save
(Note: cursor again moves to next line after new ///)

/// <summary>
/// Writes hello world
/// </summary>
/// |public void WriteHello(){}

Any help would be greatly appreciated

Incorrect for properties

Properties should not have <returns></returns>, however this is generated:

/// <summary>
/// 
/// </summary>
/// <returns></returns>           // this should not be generated
public string Foo { get; set; }

/// <summary>
/// 
/// </summary>
/// <returns></returns>            // this should not be generated
public string Bar { get; set; } = "bar";

Bug: return tag missing

What i did

public static BoolVector operator |(BoolScalar a, BoolVector b)

I typed "///" on the top to insert a template.

What i expected

/// <summary>
/// 
/// </summary>
/// <param name="a"></param>
/// <param name="b"></param>
/// <returns></returns>
public static BoolVector operator |(BoolScalar a, BoolVector b)

What happend

/// <summary>
/// 
/// </summary>
/// <param name="a"></param>
/// <param name="b"></param>
public static BoolVector operator |(BoolScalar a, BoolVector b)

Is this done on purpose, or is it a bug?

Don't open suggestion list when typing a period in an xmldoc comment

I'm not sure if this is an issue with the plugin or if it's some vscode configuration I've got wrong, but when I create a comment by typing /// and it auto-expands, and I'm filling in some description (or whatever) if I type a period it immediately pops up the auto-complete list. Inside a comment, I never want this.

If I'm typing inside a regular // or /* ... */ comment, the period does not pop up the auto-complete list. It only happens inside xmldoc comments.

Activate on Enter

Most of the comment documentors activate the comment block once the user presses Enter instead of when they type ///.

For me, I like making comment blocks that look like this:

///////////////////////////////////////////////////////////////////////////
/// Comment block that sticks out!
///////////////////////////////////////////////////////////////////////////

When I do so it attempts to make a document block.

So if you could make it so when you pressed ///Enter it gets activated instead of the current way, that would be awesome!

Please add support for generic types restrains

Hello Keisuke,

Sweet plugin! But please add support for generic types when there are restrains applied.

E.g.:

        /// <summary>
        /// Cannot auto generate fields for params and return type
        /// </summary>
        public string Test<T>(T obj) where T : class
        {
            // do something...
        }

Visual Basic Support?

I currently use this extension with C# and love it. But I am currently having to work with a Visual Basic project and would like to use it with .vb/.vba/.vbs files.

The /// doesn't trigger in any of those file extensions.

Is there a way to get this extension to work with these file extensions? Preferably triggered with ''' as ' is used in Visual Basic instead of /.

Thanks.

[Bug] Should not generate typeparam for non-generic classes

The typeparam here should not be generated, because the class is not generic:

/// <summary>
/// 
/// </summary>
/// <typeparam name="string"></typeparam>    <--- this line should not be generated
public class Foo : Bar<string> { }

Also, when generating XML documentation during building, this will result in warnings:

Foo.cs: warning CS1711: XML comment has a typeparam tag for 'string', but there is no type parameter by that name.

Please also generate documentation for generic type

Hello Keisuke,

See here, it requires that every generic type parameter have its own doc string.

/// <summary>
    /// A sample generic class.
    /// </summary>
    /// <typeparam name="S">The first generic type parameter.</typeparam>
    /// <typeparam name="T">The second generic type parameter.</typeparam>
    public class Class1<S, T>
    {
    }

Thanks

Connect to keyboard shortcut

I tried to create a keyboard shortcut for /// like so:

keybindings.json:

        "key": "ctrl+alt+d",
        "command": "editor.action.insertSnippet",
        "args": {
            "snippet": "///"
        },
        "when": "editorTextFocus && editorLangId == csharp"

but the cursor is inserted after the first / instead of on the second line after ///.

I then tried to set "docomment.activateOnEnter": true expecting the documentation snippet to appear after pressing Enter. But pressing Enter after /// does not generate the documentation snippet.

A docomment setting for a keyboard shortcut would be welcome.

Constructors can be treated as comments if they have no access modifier.

The constructor in the following code snippet isn't picked up correctly.

class A
{
    A() { }
}

because it only has its type name, no access modifier, SyntacticAnalysisCSharp.IsMethod returns false and the code falls back to a comment, so attempting to make a comment just glitches out.

Feature: Collapse XML summaries

Would be great if we could collapse XML summaries into single line (like in vs2017) or even tooltip of below declaration

Generating the Xml file

What would you recommend to use for generating the actual xml document? It does not make much sense to go back into visual studio just to rebuild and get a xml file.

Wrong value for optional parameters

I have the following:

public void Save(string data, Action<AchievementSavedResponse> onComplete = null){

}

For the second parameter, it uses null for the name attribute instead of onComplete.

/// <summary>
/// 
/// </summary>
/// <param name="data"></param>
/// <param name="null"></param>

Automatically close the xml tags.

Like Visual Studio does.
Add </tag> when the user has wrote <tag> automatically.

Thank you for your great project!

Problems together with VSCodeVim

If you use the plugin together with VSCodeVim, you can get some strange behaviour.

Example:

• Copy a comment using Visual Line Selection [V, SomeArrowKeys, y]
• go to an uncommented function and copy the register [p]

Problem:

• The VSCodeVim plugin will insert its selection
• The vscode-docomment plugin will also insert a new empty comment (probably because the old insertion contains "///" :)

The only "workaround" atm is, that the vim plugins undo history is not the same at vscode ones. So you can just press ctrl+z to undo the unwanted insertion.

Adds extra param for `Func<T, bool>`

With the following line:

public Collection<T> Filter(Func<T, bool> query) { }

When I add doc comments, I get the following:

/// <summary>
/// 
/// </summary>
/// <param name="Func<T"></param>
/// <param name="query"></param>
public Collection<T> Filter(Func<T, bool> query) { }

If I am not mistaken there shouldn't be the extra param Func<T. Instead it should look like this:

/// <summary>
/// 
/// </summary>
/// <param name="query"></param>
public Collection<T> Filter(Func<T, bool> query) { }

Comments for Constructor not working

When you type /// above a constructor the auto completion is not working. On classes, Methods etc. it is working.

Not working at all

With the latest public version of VS code, typing /// doesn't do anything. It used to create the

tags etc.

Incorrect comments generation for Destructor

Like below:

Incorrect comments generation for variables and method calls

Hello! It's can be fixed?

For this case must be

using System;

namespace EleWise.ELMA.Core.Model
{
    public class TestClass
    {
        public void Main()
        {
            ///
            var prop = "";
            ///
            Console.WriteLine(prop);
        }
    }
}

Auto-generated /// on the new line inside <summary> tag

Steps to reproduce the bug:

• create a method and generate comment on top of it by writing ///
• write 'aaa' press Enter
• now the new line is empty => no /// was generated
• write /// to fix it and watch what will happen

What I would expect is that after pressing Enter there should be another /// auto-generated on the new line.

Documentation for Properties uses the incorrect tag for the stored value

As you can see in the picture below, the <returns> tag is used for the property value but per the C# Programming Guide, it needs to be <value>. The documentation in the popups on intellisense in Visual Studio code give a malformed XML error when attempting to validate and display the docs for referenced properties.

Add Donate button

To you or any organization you care. You save my time.

3 Attributes bug

Hi man thx for fix but if i put 3 attributes which is common in asp.net

 [HttpGet]
 [AllowAnonymous]
 [Route("{cameraId}/readings")]
 public IActionResult GetReadingsForCamera(int cameraId, int offset, int limit, string orderBy)
 {
       var filter = $"id eq {cameraId}";
       return CamerasService.GetAllCamerasPaginated(offset, limit, orderBy, filter);
 }

It still doesnt generate good comments

generated comments:

/// <summary>
/// 
/// </summary>
/// <returns></returns>

As a workaround i generate them below and copy later above my attributes

Fails when trying to insert comments above attributes

For a block of code like:

[Route("{time}/{location}")]
[HttpGet]
public async Task<string> GetInfoForTime(string location, double time)

When you try to insert the comment block above the attributes, you get:

///
/// [Route("{time}/{location}")]
[HttpGet]
public async Task<string> GetInfoForTime(string location, double time)

Parameters are not returned

Dživo Jelić
I discovered a bug when you have attributes above function and you try to document the function with your line above attribute you get only summary and returns not all of the params of the function.

    /// <summary>
    /// 
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    [Route("{userId}")]
    public object Get(int userId)

Parameters not correctly identified when documenting constructor which chains to a base class constructor.

When documenting a class constructor which chains to a base class constructor, ex.

public Test(string options) : base(options)
{
}

the parameters are incorrectly identified, ex.

/// <summary>
/// 
/// </summary>
/// <param name="base(options"></param>
public Test(string options) : base(options)
{
}

I think the correct format should be this:

/// <summary>
/// 
/// </summary>
/// <param name="options"></param>
public Test(string options) : base(options)
{
}

Output document puts cursor in wrong place

When using the snippet in my code, when I do the ///<tab> shortcut, it outputs correctly, but the cursor is between slashes on the second line instead of in the blank spot. The error happens when auto documenting methods, member variables, and properties, but it works correctly on classes.

Here is a gif showing what I mean:

• Mac OS Sierra
• VSCode v1.8.1
• vscode-docomment v0.0.10

Extension issue

• Issue Type: Bug
• Extension Name: docomment
• Extension Version: 0.1.8
• OS Version: Windows_NT x64 10.0.17134
• VSCode version: 1.42.1

⚠️ We have written the needed data into your clipboard. Please paste! ⚠️

XML File document

Can the comments be configured to be saved in the xml document that I can use to configure swagger?

XML documentation file

Pls i can't find the xml documentation file in the bin directory of my project. How do i output it like in visual studio where you right click on the project -> properties -> build and check XML documentation file checkbox. Thanks.

Automatically generate base description

It would be nice if there was an option to automatically generate base descriptions as well, ie. in MonoDevelop if you try and write doc for a property named position with only get, it would generate something like:

/// <summary>
/// Gets the position.
/// </summary>
/// <value>The position.</value>
public Vector2 Position { private set; get; }

Adding /// in wrong place after pressing enter after text

When adding text to a /// line and pressing enter, the next line doesn't have the /// automatically. If I add it, it inserts a /// into the last line. It's hard to describe in words so as always here's a picture worth a thousand:

If I do this on a blank line that only has /// with whitespace after it, it doesn't happen. Hopefully this is easier to reproduce than my last bug!

Feature: Automove the cursor to summary after creation

When typing "///" the template gets created. Unfortunately the cursor stays, where he is - which is a little bit unnecessary, since i want to start editing the summary-tag in 99% of all cases.

Therefore it would be a nice feature, if the cursor could jump to the second line directly under the "<" of the summary-tag

Marketplace version of README.md has broken docomment.gif reference

When navigating to https://marketplace.visualstudio.com/items?itemName=k--kato.docomment there is a broken reference to docomment.gif. It is expecting the image to be here: https://github.com/k--kato/vscode-docomment/raw/master/images/docomment.gif (but that's a 404).

Expansion is triggering in a lot of cases when it shouldn't

1. Those cases on the current line will trigger expansions currently, which is incorrect:

   /// ///
  /// text ///

1. Expansions shouldn't trigger if the previous or next lines are already doc comments:

     /// <--should not expand
    /// <summary>

    /// <summary>
  /// <--should not expand

Autocomplete order/priority?

Is there any way I can lower the priority of the intellisense suggestions from the extension?
It is very annoying that they always show up at the top, when pressing CTRL+Space.
If not, could this be added?

Does not work for enum items

I can't create comment for enum items. Please, watch gif-animation

Included snippets are not available in VS code 1.17.2

The code/XML comments snippets included to the extension (snippets/csharp.json) are not available in VS code 1.17.2 (didn't test other versions, though). The possible reason is missing "contributes/snippets" section in the extension manifest file (package.json).

Automatically show intellisense options for tags

When starting xml tags like <see>, automatically show autocomplete options with intellisense. Autocomplete options could also include the attributes of said tag. The case I would like this for is most typically <see cref="MyType"/> or <seealso cref="ThisOtherThing"/> but I'm sure there are many more tags that other people use as well.

First Line of Methods are Commented When Adding New Argument

Steps to reproduce

1. Write the following code:

/// <summary>
/// 
/// </summary>
/// <param name="test1"></param>
public void Test(int test1)
{ }

1. Add an argument:

/// <summary>
/// 
/// </summary>
/// <param name="test1"></param>
public void Test(int test1, int test2)
{ }

1. Use [ctrl + .] on test2 to add param notes.

The param notes will be added, but the method signature becomes commented out.

/// <summary>
/// 
/// </summary>
/// <param name="test1"></param>
/// <param name="test2"></param>
/// public void Test(int test1, int test2)
{ }

It's wrong in this case !

Like below:

Cannot read property 'text' of undefined: TypeError: Cannot read property 'text' of undefined

The same error but other package: cschlosser/doxdocgen#79

Log:

[2018-06-26 22:27:54.566] [renderer1] [error] Cannot read property 'text' of undefined: TypeError: Cannot read property 'text' of undefined
    at DocommentDomainCSharp.IsTriggerDocomment (C:\Users\MateuszPaluszkiewicz\.vscode\extensions\k--kato.docomment-0.1.0\out\src\Domain\Lang\DocommentDomainCSharp.js:21:38)
    at DocommentDomainCSharp.Execute (C:\Users\MateuszPaluszkiewicz\.vscode\extensions\k--kato.docomment-0.1.0\out\src\Domain\DocommentDomain.js:20:19)
    at DocommentControllerCSharp._onEvent (C:\Users\MateuszPaluszkiewicz\.vscode\extensions\k--kato.docomment-0.1.0\out\src\Controller\DocommentController.js:52:31)
    at DocommentControllerCSharp.DocommentController.vscode_1.workspace.onDidChangeTextDocument.event (C:\Users\MateuszPaluszkiewicz\.vscode\extensions\k--kato.docomment-0.1.0\out\src\Controller\DocommentController.js:18:22)
    at e.fire (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:96:784)
    at e.$acceptDirtyStateChanged (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:685:973)
    at e.$acceptModelSaved (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:685:723)
    at e._doInvokeHandler (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:636:832)
    at e._invokeHandler (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:636:550)
    at e._receiveRequest (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:635:631)
    at e._receiveOneMessage (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:635:400)
    at c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:634:315
    at c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:637:395
    at c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:95:432
    at e.fire (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:96:764)
    at Socket.<anonymous> (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:154:338)
    at emitOne (events.js:96:13)
    at Socket.emit (events.js:191:7)
    at readableAddChunk (_stream_readable.js:178:18)
    at Socket.Readable.push (_stream_readable.js:136:10)
    at Pipe.onread (net.js:560:20)

Please make the new line in comment also start with "///"

When I Start write a new Line comment, press enter in <summary> and </summary> will create an empty line, then I need type three / character to start write comment, but, the problem is when I type three / character, the next line will be indented by another /// , which is annoying

Support for tabs indentation

I'm using tag indentation option in VS Code:

"editor.insertSpaces": false

But this extension always indent using spaces. It should read indentation information for current file from VS Code.

Only getting summary for interface methods

Hey, thanks for making this plugin. I've noticed that it doesn't seem to work for interface methods though? It only generates the summary section and not detect the parameters / return value.

/// <summary>
/// 
/// </summary>
int Generate(int level);

It does appear to work for the implemented method:

/// <summary>
/// 
/// </summary>
/// <param name="level"></param>
/// <returns></returns>
public int Generate(int level)
{
}

I've noticed that it seems consistent for method stubs.

Support delimited comment syntax /** */?

According to the C♯ specification, there's a delimited documentation comment syntax, which VS Code supports.
Does this extension support the feature?
If not, could it add support?

I cant get this extension working

I'm using VS code 1.22.2 on Windows 10
I have created ASP.net core project
Installed C# XML Documentation
configured the User settings:
// Press the Enter key to activate a command (Default: false)
"docomment.activateOnEnter": true,
// Insert spaces when pressing Tab.
"editor.insertSpaces": true,
// The number of spaces a tab is equal to.
"editor.tabSize": 4

So when I type "///" nothing happens, please assist.

Wrapping lines in the middle of text inserts /// in the wrong place.

If you hit Enter while in the middle of a sentence, it injects the '///' in the wrong place.

Using version 0.0.11