Sandcastle, /doc, and Unmanaged C++

Question

I work on a project that uses unmanaged visual C++ and a smattering of C#. We are trying to come up with a way to document our project, both the API reference, as well as some additional conceptual documents. Ideally, all of the documentation would live together in a .chm file that we could distribute with our product.

I was already familiar with Doxygen, as a long time C++ developer. Someone suggested that I look into Sandcastle as well, but I've run into a few snags.

From a number of other sources, including other posts on this site, it's well known that sandcastle does not support unmanaged C++. I did find a post that seems to indicate that you can still cram the C++ documentation into sandcastle, by adding the API reference as conceptual topics.

Using Visual Studio 2010, you can turn on the /doc option in the project settings for your unmanaged C++ project. This produces .XDC files which studio then compiles into an .xml file that goes along with your lib/dll/exe. Where I am stuck is that is unclear what exactly you can do with this xml file. Some pages I've found online suggest that you may be able to use this file for intellisense, but I've never seen that work in unmanaged C++. I was hopeful that I might be able to use this .xml file in Sandcastle Help File Builder somehow, but I can't find any examples of how that's done online, and every attempt I've made with SHFB has failed. It seems to only want MAML or HTML files if I want to add an existing conceptual help file.

So my question:

1. Is there a way to get my /doc generated .xml file into my SHFB help solution?
2. If not, what is the point of the /doc option for unmanaged C++?
3. Is there some kind of transformation I can do on my /doc generated .xml file to produce HTML or MAML which I could then import via SHFB?

Can this work, or should I just go back to Doxygen?

Answer 1

In theory, Sandcastle could be used to document unmanaged code but it would require a tool to produce the equivalent reflection data file that is currently produced by the MRefBuilder.exe tool for managed code assemblies. So far, nobody has done that to my knowledge.

I can't comment on the lack of IntelliSense for unmanged C++ since I don't use it anymore. At a guess, /doc is probably there for the managed code output assuming the same compiler is used but with a few extra command line options.

Using XSL to transform the XML comments to MAML is a possibility but, again, it's an option I'm not aware of anyone pursuing. My guess is that most opt to use Doxygen in this case since it's an established solution.

Eric

Answer 2

I have a similar situation. I need XML documentation in my C++/CLI bindings so .NET code can see them with Intellisense. But FYI, Visual Studio 2010 doesn't support XML documentation in native code:

https://msdn.microsoft.com/en-us/library/ms177226(v=vs.100).aspx

Visual Studio 2010
In Visual C++, you can add XML documentation (triple-slash) comments to your source code and instruct the compiler to output them to an .xml file. This file can then be input to a process that creates documentation for the classes in your code. The IDE for Visual C++ in this version does not support XML comments in Intellisense.

That limitation was removed in Visual Studio 2013. However, it's still an annoying ecosystem to work with if you use templates in the native code (e.g. Boost libraries):

In the current release, code comments are not processed on templates or anything containing a template type (for example, a function taking a parameter as a template). Adding such comments will result in undefined behavior.

I found your question while searching for a way to temporarily disable the XML comment parser with a #pragma or #define when including such libraries.