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?
Yes! I use them, and it is a requirement on ALL projects that I do what we include them. As for the level of detail included, it depends on the purpose of the code. At minimum all parameters and public methods will have summary information. Complex items typically have code examples, and all specifically thrown exceptions are documented.
Right now I am using SandCastle to do the documentation build and you can go to HTML or CHM without any issue at all! I've also used SlickEdit which does an on the fly parsing, and it worked great as well!
Yes, I do use this feature and think that it is a good practice for all developers to comment their api's. Once you've done this for a few apis, and as long as you stay on top of it, it's really not too hard to maintain.
Option 1: SandCastle I tried using this, but I found that there were far too many installers that I had to run and install and learn to configure. In the end, I ended up with a chm file, but really I wanted something a little lighter weight.
The upside is that the end product looks very professional. It didn't work for my situation though.
Option 2: NDoc Last time I checked, this project was not being maintained and only worked with version 1.1 of .NET.
Option 3: XSLT Someone on CodeProject has written a xslt file for this
http://www.codeproject.com/KB/XML/XMLDocStylesheet.aspx
I've tried it, and here's how it works. Build your project and drop in the xslt file into the same directory as the outputted xml file. When you double click your xml file, a formatted webpage will displayed instead of the xml document.
For me, this was the best option.
As a minimum I include comments for the public API and generate the xml file. That is enough to make intellisense work, and it also shows up in Reflector.
Personally, I don't bother with sandcastle etc - but I might for ISV projects.
We document all methods and properties with XML comments. Both for internal documentation purposes, and to be able to provide help files for our binaries. It is particularly nice to have the documentation of a method pop up in the intellisense.
We are using GhostDoc - it can provide an - often OK - default documentation, but keep in mind that GhostDoc can only document what it can infer from the method and parameter names. Therefore, our rule is that you can use GhostDoc to start the documentation; then edit it appropiately - in many cases the default documentation for parameters will be just fine. In simple cases we also just stick with the default documentation, if it makes sense.
Help files can be generated using Sandcastle (download). Also, the Sandcastle Help File Builder is a GUI that can make it easier for you to get started with Sandcastle.
I try to do it for any method that isn't glaringly obvious as to what it does. I like that it includes the documentation in the Intellisense.
I've used the SandCastle tool from Microsoft in the past to generate MSDN style documentation from Xml comments and had really good luck. Supposedly it's the tool used to generate all the .net framework docs which also happen to come from Xml comments.
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.