Can DocProject document C++ static libs?

Topics: General Questions
Jan 8, 2008 at 12:03 PM
Hi Dave,
i have a VS project for a C++ static lib with xml doc comments for which VS generates an xml file. Is it possible to produce a help file for it using DocProject? If not, can you recommend a tool, or site, for documenting unmanaged C++ VS projects that contain static libs rather than assemblies?
Thanks,
Darren.
Coordinator
Jan 8, 2008 at 7:12 PM
Edited Jan 8, 2008 at 7:13 PM
Hi Darren,

Sandcastle does not provide tools for static analysis, although if you could generate a reflection.org file (XML) from your static lib then that's all Sandcastle would need (and optionally your XML documentation). It's probably not a trivial task though. (I'm not a C++ programmer or else I might have given it a shot myself.)

But you have sparked my interest in another possibility: reverse engineering the XML documentation into a reflection.org file. It probably wouldn't be complete, and probably wrong in some places, but it might be acceptable. What do you think?

See these threads for similar discussions:


There is a list of "other" documentation tools at http://www.sandcastledocs.com; however, I don't know if any will produce documentation for C++ (and at least a few of them aren't free).

- Dave
Jan 8, 2008 at 11:24 PM
Hi Dave,

As wpcmame notes too, reverse engineering the xml doc file seems like an option, although the method prototypes in the xml don't include the parameter name - or does the doc generator write out the param tags in the correct order? It would be easy to check that... Apart from that it looks doable - famous last words.

Given how rich the xml doc is and the popularity of xml as a data exchange format, i'm surprised sandcastle makes extracting information via reflection a critical step in building help docs. Having said that, in the last release notes to sandcastle, there was mention that v2.0 might include a UReflector for extracting from header files the reflection stuff that MRefBuilder needs.

Getting it from the xml produced by VS is still a very good idea - and maybe more flexible than reflection, since VS generates xml for C#, VB and C+, managed or unmanaged. Maybe a single reverse engineering tool would do for all these - the xml generated for the C+ looks similar to the C# xml.
Coordinator
Jan 9, 2008 at 1:13 AM
Hi Darren,

Sandcastle uses reflection because it can provide at least some information that cannot be retrieved from an XML documentation file alone, such as inheritance information. Also XML documentation files do not describe the entire API - they only describe what has been documented. And in some cases, reflection can discover APIs that can't even be documented; e.g., .NET Modules.

So XML is certainly not a replacement for reflection; however, if it's all that's currently available to document C++ then it might be acceptable for now. Maybe I'll work on this in the future if the Sandcastle team doesn't provide first-class support sooner.

- Dave
Coordinator
Jan 9, 2008 at 1:20 AM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.
Jan 9, 2008 at 10:02 AM
Hi Dave,
here's and idea then. Leave the current VS produced xml doc as is and use gcc-xml (see http://www.gccxml.org/HTML/Index.html, seems to be at version 0.9 according to News) to produce an xml file that can be mapped to MRefBuilder's xml format. On the gcc-xml website it says it supports VS 8.0, so it might be possible to use it straight out of the box, which means one wouldn't have to delve too deeply into C++: hopefully it would just be a case of mapping the xml output. What do you think? Anyone interested in taking this on?
Coordinator
Jan 9, 2008 at 11:13 AM
Hi Darren,

Thanks, that's an interesting idea. I'll have to take a more in-depth look at it when I get some time.

But it's probably not worth the effort to take it that far if Microsoft is going to provide support for parsing C++ headers in the future anyway. At least if I develop a general purpose XML documentation "adapter" it will work for any type of language and platform, not just C++. And not to mention, with converting compiler-generated XML there would be no learning curve for me since only the basic managed API types would be supported. But if somebody else wants to try using GCC-XML now then I'll provide whatever support I can to help out with the conversion and integration into Sandcastle and DocProject.

- Dave
Jan 9, 2008 at 4:08 PM
That sound's like a sensible plan. I look forward to using the adapter and when the sandcastle team have time to release a C++ headers parser in v2.0.
Thanks, Darren.