What are the virtues of using XML comments in .NET?

Question

I can't understand the virtues of using XML comments. I know they can be converted into nice documentation external to the code, but the same can be achieved with the much more concise DOxygen syntax. In my opinion the XML comments are wrong, because:

1. They obfuscate the comments and the code in general. (They are more difficult to read by humans).
2. Less code can be viewed on a single screen, because "summary" and "/summary" take additional lines.
3. (removed)

What then could have been be the reasons, why XML was preferred in .NET rather that the simple DOxygen syntax?

Answer 1

1. The ide picks up the comments and shows them when using that method.
2. Everyone who programs C# is probably familiar with the XML commenting system. There's less to learn for a new hire.

I'm not saying that DOxygen isn't better, it's just that the xml commenting system is more familiar to everyone, and that goes a long way. It's just one less thing you have to train a new hire to do.

As far as leaving variables uncommented. What may be obvious to you, won't be to someone else (or to you 6 months later).

Ok now I think I see what you are asking.

1. Obfuscating comments. The color coding helps. Personally, I quickly scan past the grey text and only read what's green unless I need to read the xml text. (in my settings at least).

2. We have large monitors so we get more code on the screen in general. (It's cheaper to buy a large monitor than to retrain people generally). The other thing about this too, is that I bet you are only actively looking at one function at a time, so if that entire function fits on a page, you probably aren't suffering too much from not seeing more code. Now if the functions are long, then I could see that being a problem.

3. We put the summary comments on a single line when possible (assuming it isn't really large). That cuts down on the used space.

4. I don't know if DOxygen does this, but you can collapse the comments so they are out of the way.

Answer 2

The primary job of XML documentation is not to generate documentation. It is to provide good IntelliSense info for the client of your class. Ship the generated .xml file along with your assembly.