Documenting managed C++ code using NDoc

Posted on:May 24 2005

It is not easy to create documentation for managed C++ code using NDoc. Especially if you are mixing your code with complicated standard C++ code which uses rarely used C++ features. Just a project like Irrlicht.NET for example. My steps for creating automatic documentation for managed C++ code are the following:

1. Download the source MCXDoc, a plugin for visual studio which creates Ndoc style .xml documentation from managed C++ projects. You'll need to register at Codeproject for this.
2. Patch it, so that it doesn't crash in circumstances it gets into when parsing for example my Irrlicht.NET project. Search for
string fileName = e.ProjectItem.Name;
and replace it with
string fileName = "";
if (e.ProjectItem != null && e.ProjectItem.Name != null)
fileName = e.ProjectItem.Name;
4. Compile your patched MCXDoc and install it.
5. Compile your managed project. In the after build step, MCXDoc should run and create an .xml file.
6. Download the latest version of NDoc.
7. Create a new project in NDoc, select your compiled .NET Assembly and the generated .xml file.
8. Click on 'Namespace summaries' and insert some summaries only in the .NET namespaces, not in the native ones.
9. Set the option 'SkipNamespacesWithoutSummaries' to true. This will now stop NDoc to try to document native C++ classes and members, preventing it from trying to generate for example files with ≶ characters in it (from C++ templates) which would make it crash.
10. Done. Now you'll have some nice documentation like this.

That's a little bit work in the beginning. And it sucks. In the next VisualStudio, Microsofts compiler will be able to create these .xml files for C++/CLI projects too. So to sum up: Move from managed C++ to C++/CLI soon.

Add comment:

Posted by:

Enter the missing letter in: "Intern?tional"




Possible Codes

Feature Code
Link [url] [/url]
Bold [b]bold text[/b]
Quote [quote]quoted text[/quote]
Code [code]source code[/code]