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

Question

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

Answer 1

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()
*/

Answer 2

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.

Answer 3

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...

Answer 4

I have gotten it to work as follows:

1. Use XML style comments for your C++/CLI header entries. This means the full XML comment is required (triple-slash comments, tag at a minimum)

2. 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).

3. 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.

Answer 5

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, check out AtomineerUtils. This takes most of the work out of creating and updating DocXml or Doxygen format comments, and it works equally well for C, C++ and C# code.