Documenting managed C++ code using NDoc

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.

No comments yet:

Remember personal info?
Email (optional):
URL (optional):
Enter "layered" (antispam):
Comment:Emoticons / Textile

  ( Register your username / Log in )

Notify: Yes, send me email when someone replies.  

Small print: All html tags except <b> and <i> will be removed from your comment. You can make links by just typing the url or mail-address.
Note: If you type in your email adress above, it will be visible to other visitors, although it will be hidden for bots using javaScript.