How to turn C# Xml Doc-Comments into something useful?

Question

I want to compile the Xml documentation from a large project into some form that's easy to read and search, hopefully more convenient than browsing the raw source code. I'm not particularly worried about the end format - CHM, HTML, xyz - as long as it's usable. Being able to easily roll in (or link to) additional content would be a plus.

NDoc used to be the de facto standard, but that project shows no current sign of life (last update I can see is 19 February 2005).

Sandcastle seemed to supplant NDoc as the common standard, but I never did manage to get it running reliably, and this too seems to be a dead project. (Last release May 2008), though answers to this question seem to indicate it's not yet ready for cremation.

What's now a good way to turn the Xml Doc-Comments from a large C# project into some form of reference material?

Related questions:

• What are the C# documentation tags?
• XML Code Comments in .NET
• Is SandCastle a dead project ?

Update

I'm particularly interested in anything that has support for new .Net 4.0 goodness, as we'll be migrating the "large project" mentioned above. Also, while I'd prefer something open source, or at least free, any commercial options would be checked out as well.

Answer 1

AFAIK NDoc is still on rails and useful. XML tag comments in VS are not changed and may be that is why no need for frequent updates for the NDoc project. Anyway it is quite good.

EDIT : As there are still problems with generics in NDoc as an alternative you can check :

• NDocProc
• VSDocMan (but it is not free)
• SandCastle (You already mentioned)
• Check HERE for some others.

Answer 2

I wrote a brief blog post on getting started with Sandcastle. You'll need the Sandcastle Styles project which has several bug fixes for Sandcastle, and I also use the Sandcastle Help File Builder which is a nice VS UI for Sandcastle. SHFB and Sandcastle Styles do have regular updates.

Answer 3

Sandcastle is still around...it's true there has been no release in two years, but a new release is imminent, according to a discussion on the Sandcastle site. It's been delayed, but I imagine it will be available soon. It is expected to support .NET 4, and is free and open source.

As far as using Sandcastle, I found it to be tricky to start using. After much trial and error, I got a decent workflow for generating code documentation similar to MSDN from XML comments. I wrote up the process on my site a while ago, if you're keen to try again.

There is also docu, a lightweight and basic documentation generator. It's simple to use, so maybe you could give that a try as well.

Answer 4

The other answers here are all fine, but just two points to mention:

• Like Grant, I have a blog post about getting started with Sandcastle. This was basically a notebook which I wrote as I went along.
• As per the comments to that blog post, it's worth looking at Doxygen which supports C# comments. I found Doxygen really quick to get going with - given how easy it is to use, I think it's at least worth trying to see if you like the output.

Answer 5

Sandcastle + Sandcastle Help File Builder will do the thing for you. However, plain Sandcastle is just a pain in the...

Answer 6

Hello,

I have just forked NDoc v1.3.1 and updated it so the JavaDoc output works with Visual Studio 2008. Importing from solution or project files doesn't work yet, you have to add assemblies with the add button.

Check it out on github: http://github.com/pcpratts/NDoc4