Simplest way to add XML doc to a WinRT project

Question

We have a group of developers moving from C++ to C# and WinRT. We used D'Oxygen as part of our C++ developer builds, and I'd like to continue to have document generation as part of the developer build in C#/WinRT.

It's easy to turn on XML Doc generation, and I believe that will provide warnings for malformed tags, but without actual HTML output, I think our developers will be missing valuable feedback.

Looks like NDoc is now defunct, and I took a quick look at Sandcastle, but found it rather complex. Ideally, I'm looking for something that doesn't unduly burden developers, or require them to remember extra steps as they edit, build, test, and commit. In other words, the best solution would be something that "just happens", like a post-build step, and doesn't add significantly to each developer's build time.

If anyone has had some experience doing this in C#/WinRT, I'd sure like some advice.

Thanks in advance!

Answer 1

1. Get Sandcastle Help File Builder.
2. Create a help project for your library in the Visual Studio solution.
3. Remove Build check mark from Debug solution configuration to build the documentation project only in Release configurations, since Debug is most often used during development. For release build testing or performance testing you can either create another solution configuration or simply switch the option back and forth.
4. Build the documentation once
5. Include the documentation file in the solution so it shows up in the Pending Changes window when the file changes.
6. Kindly ask your developers to build with the release configuration that updates the documentation before check-in or use any other policy to require updating the documentation.

I don't think it makes sense to build the documentation all the time, but it helps to make it easy to do so that when you actually need an updated version - you can build it really quickly.

You can also make sure to use FXCop or StyleCop (forgot which) and configure it to treat missing XML documentation warnings as errors - at least in release builds. Doing it for debug configurations might slow down development and make changes difficult since developers often want to try things out before committing to a final implementation worth documenting.

EDIT*

Sandcastle provides various output formats as shown in the project properties:

Answer 2

I would like to mention ForgeDoc (of which I'm the developer), it could be what you are looking for. It is designed to be fast and simple, and it generates proper MSDN-like HTML output. It also has a command-line interface so you can just call it from a post-build event command in Visual Studio.

I think you should give it a try, as I would really like to hear about your thoughts.