Generate XML documentation comments for /// in Visual Studio 2010 C++

Question

I need comment my function prototype (written in C/C++) with summary, returns, param tags. How can I persuade Visual Studio to insert xml tags after three forward slashes like in C#? I found one solution. When I rename xx.h xx.cs in C++ project, I can use /// for generating xml comments (IntelliSense in xml comments works too). There must be a better way, mustn’t there? It would kill me to write it manually. I’ll grateful for every useful comment.

/// <summary>
/// 
/// </summary>
/// <param name="aa"></param>
/// <returns></returns>
bool function1(TypeX aa);

Solution 1

This functionality isn't buit-in. You can try using Visual Studio add-ins. I haven't used Atomineer Utils Pro Documentation myself, but it looks promising. It generates documentation comments and supports C++. It costs $10 though.

Solution 2

CppTripleSlash creates xml doc comment stubs in c++ files when /// is typed, similar to what is available for c# in visual studio. This also has some basic intellisense for completing XML doc comments.

Solution 3

GhostDoc will now insert XML comments for C++ elements. Just put the cursor on an element and press Ctrl+Shift+D.

GhostDoc has a free version for personal use that will already do this.

Solution 4

For C++/CLI

These instructions work well for Visual Studio 2015 Update 2.

First, turn XML documentation on. This generates a metadata file, which means that the comments will be visible externally, including C#.

Next, as per the answer from @tcb, install CppTripleSlash. Restart Visual Studio, and you should be good to go.

Solution 5

This feature is finally coming to Visual Studio 2019 16.6 as native feature (along with auto generated headers and C++20 full support):

https://docs.microsoft.com/en-us/visualstudio/releases/2019/release-notes-preview

After so many years...

View more solutions

Comments

[Steve Guidi]

This is a result of the C++ and C# language teams using different Intellisense engines. To the best of my knowledge, you won't be able to get the C# auto-completion when typeing /// in a C++ file.

[user471571]

No. When a file have cs extension, I can. Renaming a file for writing xml comment is not suitable, but it can help.

[Jesse Chisholm]

While I agree that there ought to be a way to get the IDE to do it for you, in regards It would kill me to write it manually. Really? If you are being sufficiently verbose in the text that goes in these documentation blocks, (so you can understand how to use the code after you've forgotten that it was you that wrote it) then the overhead of the /// and the xml tags isn't really that much. :-) -- Or, to egregiously misquote the movie The Thirteenth Warrior "Learn to type faster." :-) :-)

[Kotauskas]

@JesseChisholm It really is a problem. I literally wanted to stop using C++ at some point only because of this.

[Charles]

Atomineer Utils is the product you want. After testing the free trial for 10 minutes, I gladly paid the $10. It functions just like you'd expect if you've worked with C# or VB.

[Contango]

This works brilliantly in C++/CLI for Visual Studio 2015 Update 2. Requires a restart of VS before the functionality kicks in.

[j00hi]

I can't recommend it. It asks developers to change their code in order to work in all cases which is a no-go for a tool which only adds comments. Furthermore, it does not behave as what we are accustomed to with C# and sometimes produces more work. For instance, it doesn't insert /// in new lines and stupidly inserts <summary> tags every time you enter triple slashes.