Use SHFB with C++ unmanaged

[h-ancher]

Hi,

I try to use your great tool with C++ unmanaged. I have a little project in C++ with this /doc compiler option, and when I add the only XML file to SHFB, it claim for binary or project. When I add the binary or the project, SHFB claim for API selection, and it's totally impossible because the C++ native binary can't be analysed by SandCaslte: SHFB: Error BE0033: No APIs found to document. See error topic in help file for details.

My question is: Does it possible to deactivate the part of SHFB who try to analyse binary to find API requirement and use only the XML file?

I try to do that with the components and plugins without any success. I use the last version, outside Visual Studio.

Thanks for your answer.

[EWSoftware]

The help file is produced from a combination of the XML comments and the reflection information generated by parsing the managed code assemblies. If there were a way to produce an equivalent copy of the reflection data file from the unmanaged assemblies you could use it but I'm not aware of any way to do that. For unmanaged C++, you'll need to use a tool like Doxygen.

[h-ancher]

Yes, this is an alternative, but Doxigen isn't very pleasant to use, to verbose.....

I hope it will possible to use the converter and the template to simply use the XML file, without any relation with the binary. too bad that's can't be done easily.

[h-ancher]

Still, here is any way to produce the "reflection" needed by SandCastle to link element to XML? For example, by parsing the C++ code? (with a plugin)

I try to transform my XML documentation generated by VS for my C++ project with a XSLT schema, without any reflection information, but the schema I've found aren't so "cool" like yours (like VS213 style).

[EWSoftware]

A plug-in that replaces the build step that generates the reflection data file is certainly possible. Unfortunately, I'm not aware of any way to parse the unmanaged C++ assembly. The only way to do it that I'm aware of would be like Doxygen and parse the actual source code.

By doing that, you could probably gather enough info to generate the reflection data file or perhaps enough to create a stripped down version for use with a custom presentation style that's oriented towards documenting unmanaged code. However, that's a pretty significant undertaking and isn't one I can take on. My C++ days are well behind me and I wouldn't know where to start as far as parsing C++ code anymore.

If someone like you wants to give it a try, I can certainly help with info on how to create the plug-in and provide info on the minimum set of reflection data file elements needed etc. Given a reflection data file, I could create a presentation style for it. That part I do know well enough to handle.

[h-ancher]

Why not ?

I could try to make a plug-in, if you describe the way to do it. Maybe you can provide a sample to develop a plug-in, and an article to explain the format of reflection data file.

[EWSoftware]

As a starting point, there's a topic on creating plug-ins for SHFB. There's a Visual Studio template that can be used. The help topic walks you through what to do.

For this plug-in you'd want to use the InsteadOf execution behavior to replace the GenerateReflectionInfo build step. The Execute method of the plug-in would parse the C++ source code and generate the reflection information file.

As far as configuration items, the folder containing the source code would be one possible item. Instead of a plug-in configuration, I suppose you could just use the documentation sources as the input and get the source file information directly from the C++ MSBuild project files.

Regarding the reflection information file, there's a schema for the one output by MRefBuilder. For this, it probably doesn't have to match exactly because you may not be able to get all the same info.

As a starting point, I'd suggest perhaps creating the plug-in and seeing if you can create the parser that can get namespace, type, member, and method parameter information. I can supply an example reflection data file with more details about what would be needed by a potential presentation style once you get to that point.

[h-ancher]

That's great, thanks for the explanation.

I will try to make a plug-in to parse project files, and extract metadata required by the next step. I keep you it touch when my plug-in will good enough to start massive tests.

[Leadwerks]

I am interested in the same thing.