Documenting C++/CLI library code for use from c# - best tools and practices?

Documentation C++ Cli Doxygen Documentation Generation

Documentation Problem Overview

I'm working on a project where a c++/cli library is being used primarily from a c# application.

Is there any way to make the code comments in c++/cli visible to c# intellisence within visual studio?

Assuming there isn't, what would be the best way to document the c++/cli code to enable its easier use from c# (and within c++/cli of course)? What is you opinion on XML comments vs doxygen vs other tools (which)?

Documentation Solutions

Solution 1 - Documentation

I have gotten it to work as follows:

Use XML style comments for your C++/CLI header entries. This means the full XML comment is required (triple-slash comments, <summary> tag at a minimum)
Make sure that the C++ compiler option Generate XML Documentation Files is on. This should generate an XML file with documentation with the same name as your assembly (MyDll.xml).
Make sure that the C# project references your assembly MyDll.dll where MyDll.xml is also present in the same folder. When you mouse over a reference from the assembly, MS Visual Studio will load the documentation.

This worked for me in Visual Studio 2008 on an assembly built for .NET 3.5.

Solution 2 - Documentation

DocXml has the major advantage of being supported by VS (syntax colouring, intellisense, automatic export to the XML files). The Doxygen tools can read DocXml format so you can still use them with this format too.

To help you generate tidy and accurate Doc comments with a minimum of effort, you might like to check out my addin AtomineerUtils. This takes most of the work out of creating and updating DocXml, Doxygen, JavaDoc or Qt format comments, and it supports C, C++, C++/CLI, C#, Java, JavaScript, TypeScript, JScript, UnrealScript, PHP and Visual Basic code.

Solution 3 - Documentation

Interesting. After trying several methods, it's looking like the intellisense between a Managed C++ project and C# doesn't work.

The following example will give you proper intellisense in the C++ environment where it is declared, but referencing the object in C# shows nothing:

// Gets the value of my ID for the object, which is always 14.
public: virtual property int MyId
{
    int get() { return 14; } 
}

XML comments don't work either. I would guess that this is either a bug, or requires something I can't figure out. Judging from the lack of answers on this question, perhaps a bug.

As far as documentation generation, I'd recommend going the path of XML documentation. Doxygen supports reading XML documentation which is mostly identical to the standard XML documentation for C#. It does tend to add extra lines just for tag openings and closings, but is much more readable in my opinion than the following doxygen alternative:

//! A normal member taking two arguments and returning an integer value.
/*!
  \param a an integer argument.
  \param s a constant character pointer.
  \return The test results
  \sa Test(), ~Test(), testMeToo() and publicVar()
*/

Solution 4 - Documentation

You are right. It doesn't work. The C++ build will add its IntelliSense information into the master .ncb file, and you will get the autocompletion of method names, etc. However, you are correct in that you will be unable to get the "comment" description about each method, etc.

Solution 5 - Documentation

You'll probably have a lot of value taking a look at Doxygen. And then look up Doxygen.NET - which is something we wrote for our own use which builds "Object Hierarchies" from the XML file outputs from Doxygen...

Content Type	Original Author	Original Content on Stackoverflow
Question	Hrvoje Prgeša	View Question on Stackoverflow
Solution 1 - Documentation	Zoinks	View Answer on Stackoverflow
Solution 2 - Documentation	Jason Williams	View Answer on Stackoverflow
Solution 3 - Documentation	Will Eddins	View Answer on Stackoverflow
Solution 4 - Documentation	maxwellb	View Answer on Stackoverflow
Solution 5 - Documentation	Thomas Hansen	View Answer on Stackoverflow