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.

However, we are interested in:

• Do you see any benefits in the generated layout or documentation structure using something other than DoxyGen? We create documentation for external developers who have experience with C # and the .NET platform. Maybe they are used in a specific documentation format?
• How well is DoxyGen integrated with Visual Studio? Is there something that allows you to generate documentation with one click from the IDE?
• Is any other documentation system compatible with Visual Studio?

Answer 1

The standard way to document C # code in Visual Studio is to comment on the XML documentation . In my opinion, this is the best way to use C # code, because support for this is already integrated into Visual Studio (automatic completion of the comment tag, warning about missing or incorrect parameters, ...). To document a method, simply enter three slashes ( /// ) in front of the method body, and Visual Studio will introduce an empty comment template to populate, for example:

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

You can configure Visual Studio to create an XML file from all comments, which will then be passed to a documentation generator, such as Sandcastle . If you want to use Doxygen , this is not a problem, because it supports parsing XML comments.

To summarize: I would recommend using XML comments on special Doxygen comments for C # code. So you have all the options. You can create documentation in the standard Doxygen format that your organization is familiar with (because Doxygen supports XML comments), plus you have the option to generate documentation in a format known to .NET developers (with Sandcastle and FileBuilder with Sandcastle support ).

Oh, and also try GhostDoc ...

Answer 2

There are several documentation options:

• Microsoft free path. Use DocXml documentation comments and then Sandcastle or a similar tool to create MSDN-style documentation. The advantage of this is that Visual Studio recognizes the documentation (syntax - colorizes the comments), and the documentation is immediately picked up by the Intellisense system (so if you hover over the method you are calling, a tooltip will display a summary and information about the parameters that you entered in doc comments)

• Free Doxygen System. This is easier to use and more flexible but not supported by Visual Studio, so you lose the benefits of intellisense coloring and syntax. Doxygen, on the other hand, parses the DocXml format, so you can get the best of both worlds by using the DocXml format with Doxygen to create external help.

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

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

I also suggest you look at my add-on, Atomineer Pro Documentation , which allows you to generate and update DocXml, Doxygen, Qt or JavaDoc Comments much faster and easier in VS - the perfect complement to Doxygen and Sandcastle.

Answer 3

Doxygen can consume C # doc comments (///) just fine. Document your code as usual 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 is not integrated into the visual studio, it comes with a simple IDE and can be trivially written as a custom external tool. Personally, I have included doxygen in my build scripts and it works flawlessly.

Finally, doxygen is cross-platform (which is an advantage if you ever need a port for Mono) and is significantly faster than SandCastle (both for installation and for launch).

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

Answer 4

.NET developers are used for the documentation format similar to MSDN used in VS help. It is preferable to integrate directly into the VS-help, since it provides some bonus functions, such as F1 help, filters, unified index and TOC. Several tools have already been mentioned. I would add another commercial solution with one click, VSdocman .

The comments on XML documents are excellent because they are also automatically used in IntelliSense and Object Browser quick info.

Answer 5

Visual Studio does not have an integrated documentation system.

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

There are several tools for C # or .NET documentation, and the most commonly used (as far as I know) Sandcastle .

Finally, you can check out this blog post , which provides a small Python script that converts some C # tags to Doxygen.