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

Visual Studio does not have an integrated documentation system.

If you want to stay consistent with the other languages, you can try using Doxygen with the Doxycomment Addin for Visual Studio.

For the C# or .NET documentation, several tools exists and the most used (to my knowledge) is Sandcastle.

Finally, you can check this blog entry that provides a small Python script that converts some C# specific tags into Doxygen ones.

Answer 2

There are several options for documentation:

• The free Microsoft way. Use DocXml documentation comments, and then Sandcastle or a similar tool to build MSDN-style documentation. The advantage of this is that Visual Studio recognises the documentation (it syntax-colours the comments) and the documentation is instantly picked up by the Intellisense system (so if you hover your mouse pointer over a method you are calling, the tooltip will display the summary and parameter information that you entered in the Doc Comment)

• The free Doxygen system. This is easier to use and more flexible, but not supported by Visual Studio, so you lose the intellisense and syntax colouring advantages. On the plus side, Doxygen does parse the DocXml format, so you can get the best of both worlds by using the DocXml format with Doxygen to generate the external help.

• Commercial products like DocumentX, which allow you to edit the documentation in a WYSIWYG window.

I would recommend starting with DocXml comments and Doxygen to generate the external help, as that's the cheapest and easiest way to get started, and retains all the best features of VIsual Studio (intellisense etc).

I'd also suggest you look at my free add-in, AtomineerUtils, which makes the generation and updating of DocXml or Doxygen format comments much faster and easier within VS - an ideal complement to both Doxygen and Sandcastle.

Answer 3

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...

Answer 4

.NET developers are used to MSDN-like documentation format used in VS help. Preferably directly integrated in VS help as it gives some bonus features like F1 help, filters, unified Index and TOC. Several tools were already mentioned. I would add one more commercial one-click solution, VSdocman.

XML doc comments are great because they are automatically used also in IntelliSense and Object Browser Quick Info.

Answer 5

Doxygen can consume C# doc comments (///) just fine. Document your code as normal and run doxygen to scan them into standalone html, chm and pdf files. This is by far the most versatile, simple and non-invasive approach.

While doxygen isn't integrated into visual studio, it comes with a simple IDE and can scripted trivially as a custom external tool. Personally, I have integrated doxygen into my build scripts and it works flawlessly.

Finally, doxygen is cross-platform (which is an advantage if you ever find a need to port to Mono) and is significantly faster than SandCastle (both to setup and to run).

This is an example of doxygen output for C# code on a ~1Mloc project: http://www.opentk.com/files/doc/annotated.html