XML Code Comments in .NET

Question

How much do you use the XML comments in your code files, and how do you use them? I've seen that you can use them to generate XML documentation, but can this XML documentation be used to generate an HTML help file or schema file for your code?

Also, have you used any auto-generating comment tools (i.e. GhostDoc), and what are your impressions?

Thoughts?

Answer 1

XML documentation by itself can be useful if you distribute the XML files from the build along with the DLLs. This way, any consumers of the API have useful information available from within the IDE (via Intellisense or the object browser).

Now perhaps the greatest use of XML comments is the generation of help documentation from these built XML files. Microsoft Sandcastle is the way to go regarding this at the moment. It can produce HTML Help 1 (i.e. CHM) files or HTML Help 2 (i.e. help files that can integrate into Visual Studio Help). (Note: In the past, the option of NDoc may have seemed more appealing - and some people still use it - but Sandcastle seems to be the official and recommended method at this moment, especially given that it's reasonably stable and complete enough for almost any purpose.) See the SandcastleDocs website to get started (this was unofficially put together by one of the developers at Microsoft I believe). In particular, you'll want to check out the Sandcastle Help File Builder GUI - in my experience I've found it to be an excellent tool.