Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

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

like image 628
Hrvoje Prgeša Avatar asked Jun 24 '09 19:06

Hrvoje Prgeša


People also ask

Should I use C++/CLI?

If you want to interface with lots of unmanaged code, it might be easier to use C++/CLI. You need C++/CLI if you want to write a DLL that is callable from an unmanaged language. For example I have DLLs written in C# that are called by ADA. ADA has to link with an unmanaged library, and that is C++/CLI.

What does C++/CLI stand for?

C++/CLI is variant of the C++ programming language, modified for Common Language Infrastructure.

What is the difference between C++ and C++/CLI?

C++ runs directly as binary complied for your hardware. C++ cli is a c++ extension that is used to interface with the MS common language runtime. It complies to IL normally and is executed inside the . net runtime.

How do I create a CLR project in Visual Studio 2022?

To create a CLR console app projectOn the menu bar, choose File > New > Project. In the New Project dialog box, select the Installed > Templates > Visual C++ > CLR node, and then select the CLR Console Application template.


3 Answers

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

like image 163
Zoinks Avatar answered Oct 16 '22 09:10

Zoinks


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.

like image 20
Jason Williams Avatar answered Oct 16 '22 07:10

Jason Williams


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()
*/
like image 1
Will Eddins Avatar answered Oct 16 '22 08:10

Will Eddins