26

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);
user471571
  • 263
  • 1
  • 3
  • 7
  • 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. – Steve Guidi Oct 30 '10 at 17:25
  • 1
    No. When a file have cs extension, I can. Renaming a file for writing xml comment is not suitable, but it can help. – user471571 Oct 30 '10 at 17:51
  • 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." :-) :-) – Jesse Chisholm Aug 22 '15 at 00:17
  • @JesseChisholm It really is a problem. I literally wanted to stop using C++ at some point only because of this. – Kotauskas Jul 22 '18 at 19:13

8 Answers8

8

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.

tcb
  • 4,408
  • 5
  • 34
  • 51
  • This works *brilliantly* in C++/CLI for Visual Studio 2015 Update 2. Requires a restart of VS before the functionality kicks in. – Contango Apr 16 '16 at 11:52
  • 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 `` tags every time you enter triple slashes. – j00hi Jul 18 '18 at 11:44
7

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.

Athari
  • 33,702
  • 16
  • 105
  • 146
  • 2
    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. – Charles Nov 05 '10 at 18:35
6

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.

Daniel A.A. Pelsmaeker
  • 47,471
  • 20
  • 111
  • 157
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#.

enter image description here

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

Community
  • 1
  • 1
Contango
  • 76,540
  • 58
  • 260
  • 305
1

Have a look at this add-in: GhostDoc

Florian
  • 380
  • 3
  • 20
1

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://learn.microsoft.com/en-us/visualstudio/releases/2019/release-notes-preview

After so many years...

Andrey Borisovich
  • 191
  • 1
  • 4
0

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)

Community
  • 1
  • 1
Jesse Chisholm
  • 3,857
  • 1
  • 35
  • 29
0

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.

Christian St.
  • 1,751
  • 2
  • 22
  • 41