Home/ Questions/Q 9272963
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-06-18T15:59:21+00:00

We have a group of developers moving from C++ to C# and WinRT. We

  • 0

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!

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team
    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.

    Configuration Manager start
    Configuration Manager with documentation Build disabled for Debug config
    Solution structure that makes it easy to see and check in the .chm file updates

    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:

    enter image description here

    • 0