What document compiler should be used with C# 3.0 XML documentation comments ?

Question

Hi,

I am wondering what documentation compiler other developers use to transform the C# 3.0 XML comments into documentation. I had experimented with the Microsoft supplied tool in Visual Studio 20005, but am currently using Visual Studio 2010 Beta 2. I have heard of "Sandcastle", which was apparently used for VS 2010 Beta documentation (see: http://blogs.msdn.com/sandcastle/), but have not tried it out.

Thanks,

Scott

Answer 1

We use Sandcastle Help File Builder, which puts a friendlier front end on Sandcastle (and also supports stuff like compiling in how-to pages written externally from the XML docs).

Answer 2

A popular alternative is Doxygen, which supports its own formats, JavaDoc format and the Visual Studio DocXML comment format.

You might also like to check out AtomineerUtils for creating/updating the comments better and faster in the first place.

The best format to use is /// (triple-slash) with XML documentation, because Visual Studio will syntax colour the different parts of the comment text, and the documentation (summary, returns and parameters) is immediately picked up by the Intellisense engine and displayed as tooltips over the code as you are typing in calls to your methods etc.

Answer 3

I personally use NDoc3 (a continuation of the discontinued NDoc) which is pretty easy to handle. I haven't tried Sandcastle yet.