Visual Studio with DoxyGen for documentation, or should we use something else?

Question

We are currently using DoxyGen to document code written in C/C++, PHP and Java. To have a consistent environment it would be nice to use it for C# documentation as well.

However we are wondering:

• Do you see any advantages in the generated documentation layout or structure using something other than DoxyGen? We are generating documentation for external developers who are experienced with C# and the .NET platform. Maybe they are used to a certain documentation format?
• How well integrated can DoxyGen be with Visual Studio? Is there something which enables a one-click generation of documentation from inside the IDE?
• Is some other documentation system more integrated with Visual Studio?

Answer 1

The default way of documenting C# code in Visual Studio is by XML documentation comments. In my opinion this is the best way to go for C# code because support for this is already integrated in Visual Studio (comment tag auto completion, warning about missing or incorrectly spelled parameters, ...). To document a method, just type three slashes (///) in front of the method body, and Visual Studio will insert an empty comment template for you to fill, like so:

/// <summary>
/// 
/// </summary>
/// <param name="bar"></param>
private void Foo(int bar)
{
    // ...
}

You can configure Visual Studio to generate an XML file from all the comments, which would then be fed into a documentation generator like Sandcastle. If you want to use Doxygen, this is no problem as it supports parsing XML comments.

To sum up: I would recommend to use XML comments over special Doxygen comments for C# code. This way you have all the options. You can generate documentation in the standard Doxygen layout your organization is familiar with (becauses Doxygen supports XML comments) plus you have the option to generate documentation in a format known to .NET developers (with Sandcastle and Sandcastle Help FileBuilder).

Ah, and also try GhostDoc...