Jun 24, 2010 at 9:48 PM
Edited Jun 24, 2010 at 9:51 PM
I was trying to achieve the same a few years ago. The challenge was to have MSDN-like documentation from both C++ and managed C++ (version 1) sources. The most widely used tool to generate it was NDoc but it needed a .NET assembly and gathered XML comments
to work. C++ compiler does not produce any assembly and managed C++ did not produce gatehered XML comments at those times.
I went the way Eric suggested. Doxygen can produce XML instead of other output formats. I patched doxygen not to choke on the managed C++ and generate one big XML file. Then I wrote a XSL converting the doxygen's XML schema to the NDoc's one. I had to patch
NDoc too, not to require an assembly but infer a "fake reflection" from the XML file. It worked well for managed C++ (if you accepted different comment syntax), worse for C++. (You lose header and library file structure and then most of the C++ language
which you can only "translate" to .NET primitive types as long as it is possible. The documentation was unusable for a sane C++ developer.)
The project I was working on was stopped earlier than I could finish the documentation tools. I think that for (unmanaged) C++ code it is better to use doxygen. It produces results offering more covenient browsing for C++ developers. Managed C++ (version
2) compiler gathers the expected XML comments but when I shortly tried to play with it, Sandcastle did not recognize the linked binary as a pure .NET assembly. (?)
It makes sense to generate .NET-like documentation for purely managed C++ projects. Sandcastle does not actually need a binary assembly for most of its work. At the beginning, it produces a big reflection XML extracted from the input assembly and then works
with the XML only. (It is also one of the reasons why we curse this design for its slowness and greediness.) If you get somehow the reflection XML it will be enough. I don't know why the MkrefBuilder rejected the binary and if it is possible to patch it or
if the problem is in the .NET reflection implementation. I wrote once the reflection XML by hand for a testing assembly but you would need a tool for a real project.
After you get reflection XML and comment XML for your managed C++ assembly, you would need to patch SHFB to accept assemblies represented as reflection XML files (I did it) and you can produce the documentation as you are used to with C# assemblies. Quite
a little work though...