Sample using C/C++ project ?

Topics: User Forum
Jun 23, 2010 at 10:08 PM
Edited Jun 24, 2010 at 12:46 AM
I'm a doc writer, and in a previous version of our software I was able to build a managed code guide simply by importing the Visual Studio solution file into the Sandcastle Help File Builder and tweaking the formatting style. I have just been asked if I can take a directory filled with .cpp files that are built into a DLL using Visual Studio, and use Sandcastle to document each of these functions. I've gotten far enough to add <summary> and <remarks> tags to some of the routines, and set C/C++ output properties to generate XML documentation. When I build the project, I end up with .sbr files for each of the .cpp files. I also have MYLIBRARY.dll and MYLIBRARY.xml. The .xml file includes the few summary and remarks that I added to the source. I've added MYLIBRARY.dll and MYLIBRARY.xml as document source to the Sandcastle Help File Builder. However, when I do Documentation > Build Project, I get the following error: SHFB: Error BE0033: No APIs found to document. See error topic in help file for details. This initially throws me off because I see text in my .xml file, but can't figure out why it isn't being converted to a final .chm file. When I look up the error in the help file, it says that I should include a project or solution file. However, I'm using Visual Studio 2008. When I add the project file, I get an error that C++ project files prior to Visual Studio 2010 are not currently supported. Is there a step-by-step set of instructions that will help me to document this C++ code that is currently being built using Visual Studio 2008? I can probably install Visual Studio 2010 and build a project file from there, but then I'll be out of synch with the version of Studio being used by the engineers.
Jun 24, 2010 at 2:08 AM

Note that Sandcastle will only document managed code.  If the assembly is native code (no .NET code at all), it won't produce any output.  If it is managed code but nothing was found to document, it could be that all of the classes are private.  If that's the case, setting the DocumentPrivates and/or DocumentInternals SHFB project properties to True will get them to show up.  Note that this may include more stuff than you want.  If that's the case, you can use the ApiFilter to remove the unwanted members.



Jun 24, 2010 at 12:48 PM
Edited Jun 24, 2010 at 12:53 PM
I changed the project from native to managed by doing the following:

Configuration properties > General > (added Common Language Runtime Support /clr)
Configuration properties > C/C++ > Code Generation (changed Runtime Library from /MT to MD)

After I rebuilt, I returned to Sandcastle and still got the error: SHFB: Error BE0033: No APIs found to document

So, I changed Project Property > Visibility > DocumentPrivates to True then I at least get a .chm file. But, even though I get (a lot of) something, my functions still don't appear.

Jun 24, 2010 at 3:25 PM

It's been many years since I've done any C++ so I'm not familiar with the compiler options anymore.  It sounds like your project isn't really managed code.  Perhaps you can find developer to help you out to see if that is the case.  If so, you may need to find an alternate means of documenting that project.



Jun 24, 2010 at 5:46 PM
Eric: Thanks for the quick responses. Maybe you can help in in a different way...

I DO end up with a .xml file, and it's got everything I'd like to have in my eventual chm help file.

Is there a way that I can set up a TOC or something that simply says how this information (summaries/parameters/remarks) should be organized without needing the assembly?


Jun 24, 2010 at 7:13 PM

Sandcastle requires the assembly to obtain the information about the namespaces, types, and members so without that, there's no way to generate a TOC or help topics.  You might check out a documentation tool called Doxygen which is written for non-.NET code such as C, C++, Java etc.  I think it might support XML comments but I'm not sure.



Jun 24, 2010 at 8:48 PM
Edited Jun 24, 2010 at 8: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...

   --- Ferda