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!

Scott Smith
  • 3,900
  • 2
  • 31
  • 63

2 Answers2

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.

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

Filip Skakun
  • 31,624
  • 6
  • 74
  • 100
  • Thanks for your detailed answer. I'm going to mark yours as correct. However, I've found Sandcastle to be prohibitively slow (thus making it NECESSARY to only run it in a Release build). Also, I would have preferred an HTML-only output format. The CHM output has the disadvantage that if the developer has the file open, build fails due to file locking. I really liked D'oxygen's output and ease of use... – Scott Smith Feb 09 '13 at 00:21
  • I think it does output HTML and only then compiles it into a CHM. There are probably some config options to change the output format. – Filip Skakun Feb 09 '13 at 00:27
  • Updated answer - in project properties I see CHM/HxS/MSHC/HTML formats – Filip Skakun Feb 09 '13 at 00:30
1

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.

Balazs Tihanyi
  • 6,659
  • 5
  • 23
  • 24