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:
Can this work, or should I just go back to Doxygen?
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