Generate XML documentation comments for /// in Vis

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);

Answer 1

This applies to C++/CLI

Another way is to use ILSpy to convert C++/CLI code to C#. Then, in C#, you're able to write comments with IntelliSence support. Then just copy the comments into the C++/CLI project, compile and you're fine :-)

Configure Visual Studio (2013) to use ILSpy

1. Download the ILSpy binary
2. Add a new tools entry in Visual Studio by opening "Tools / External Tools / Add".
3. There enter the path to ILSpy.exe for Command, $(TargetPath) for Arguments and $(TargetDir) for Initial directory.
4. Apply and close the window.
5. (A new entry shows up in the Tools tab)
6. Create a new empty C# project.

Use it

If you then open any file of the C++/CLI project and activate the new entry in the Tools tab, a window (ILSpy) appears displaying your assembly converted to C# code. Copy that code to a file located in the C# project and write XML comments.

Answer 2

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.

Answer 3

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.

Answer 4

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.

Answer 5

In Visual Studio 2010 C++, you can define macros to insert things for you.

Define a macro to insert the basic function header summary line.

/// <summary> </summary>

Another for an empty param line, another for a returns line.

/// <param name=""> </param>

and

/// <returns> </returns>

That will cover most of your needs with just three macros. If you use them enough then add a macro for /// <remarks></remarks> and /// <exception name=""></exception> and <see cref=""/> and any you don't use enough to make a macro for you would need to enter manually.

Yes, you will have to type the name of the parameter in manually. :) Macros can't do everything. :)

See: MSDN : VS2010 : How to Record Macros

See: MSDN : VS2010 : How to Run macros

UPDATE: I was unaware of these threads when I wrote this answer:

SO: Macros don't run in VS2010

MS: Macros broken in VS2010 by security fix Feb 2014 (with a suggested workaround)

Answer 6

Have a look at this add-in: GhostDoc