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?

Christian · Accepted Answer · 2021-02-15T13:48:01.150

55

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

edited Feb 15 '21 at 13:48

answered Jan 08 '10 at 16:06

Christian

9,914
6
45
52

3

I Love GhostDoc - definetly worth trying out! – Henrik Gering Jan 14 '10 at 16:30
1

VS cannot generate the XML file for web sites and web services, which imho in this day and age renders the Microsoft approach useless for what I do. DoxyGen is the way to go. – cdonner Feb 19 '10 at 03:13
2

Who was the really smart person who decided to use single line comments for a doc comment? – alternative Apr 10 '11 at 22:02
23

My recommendation is to stay away from GhostDoc. The auto-generated documentation created by it can provide you with some guidelines for the method's functionality, but from my personal experience, it's not worth it. Programmers tend to get lazy about writing the function documentation and just use the predefined GhostDoc text, which in fact troubles future development, because the code gets full of garbage documentation (a documentation that doesn't explain nothing) and makes you lose your time reading nonsense comments. – Canella Feb 15 '12 at 10:50
2

@Canella It's highly improbable that any tool can generate 100% meaningful comments about your code however GhostDoc is useful in creating the initial comment layout afterwhich you can go in and fill in the blanks and/or alter what was generated. Much better than nothing. – Apr 23 '15 at 02:03
I agree with you about the tools being imperfect @MickyDuncan. But for the initial comment layout, I would just type /// above the method/class/member that I wanted to comment, and VS (or ReSharper - can't remember which one was responsible for this) would replace it with a default template for comments, much like GhostDoc but without the comments text. – Canella May 30 '15 at 03:25
3

@MickyD,@Canella: One key advantage of the GhostDoc tool is that it encourages using meaningful method names. When these are chosen appropriately you in fact get your comment mostly for free sinc ethe default generated comment makes sense. This is paticularly useful in work environements which enforce comments/documents using tools such as stylecop. – shelbypereira Apr 15 '16 at 08:20
as written in other answers with lower votes, currently doxygen also understand the xml comments described above without problems https://www.stack.nl/~dimitri/doxygen/manual/xmlcmds.html – YaP Apr 18 '16 at 16:07
@shev72: Any documentation that can be inferred from the member name is useless documentation - it's the very thing that makes using GhostDoc (lazily) a bad idea because it bloats documentation with worthless noise. Where GD shines is providing a better template for higher quality material (providing the coder bothers to write it, of course!). I think it also does useful things such as copying info from interfaces to implementations. – Bob Sammers Oct 27 '17 at 14:09

Jason Williams · Answer 2 · 2012-04-11T22:12:40.850

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 add-in, Atomineer Pro Documentation, which makes the generation and updating of DocXml, Doxygen, Qt or JavaDoc format comments much faster and easier within VS - an ideal complement to both Doxygen and Sandcastle.

I mean that if you are using Visual Studio, it doesn't cost you anything to use the XmlDoc features that are built in (as opposed to buying an additional 3rd party product to get started). But in any sense, Microsoft produce a vast number of free tools. — Jason Williams, Jan 08 '10 at 20:24
@EwanTodd XML documentation works just as well in C# Express (which is free). — Camilo Martin, Apr 06 '12 at 07:28
as written in other answers with lower votes, currently doxygen also understand the xml comments described above without problems stack.nl/~dimitri/doxygen/manual/xmlcmds.html — YaP, Apr 18 '16 at 16:08

score 17 · Answer 3 · edited Jun 11 '20 at 10:59

17

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: https://web.archive.org/web/20160313075951/http://www.opentk.com/files/doc/annotated.html

edited Jun 11 '20 at 10:59

Mercerbearman

80
9

answered Apr 19 '10 at 21:06

BlackStar

213
2
7

2

Thanks for providing an example. That example makes me avoid losing time with Doxygen, since the documentation it produces really doesn't please me :) – Camilo Martin Apr 06 '12 at 07:31
3

The link is broken. – shawn1874 Dec 28 '17 at 18:56
1

DOXYGEN CAN CONSUME C# DOC COMMENTS???? My god, I just spent two hours looking for stuff and that sentence just made my day – Gaspa79 Jul 25 '19 at 18:00

score 1 · Answer 4 · answered Jan 08 '10 at 15:44

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.

answered Jan 08 '10 at 15:44

Laurent Etiemble

27,111
5
56
81

2

What do you call Visual Studio's XML documentation? – Ed Altorfer Jan 08 '10 at 16:41
It is XML documentation, not a browsable documentation like the one generated by Doxygen. You have to process it with Sandcastle for example, before use. – Laurent Etiemble Jan 08 '10 at 22:21

score 1 · Answer 5 · answered Jan 08 '10 at 16:37

1

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

answered Jan 08 '10 at 16:37

Peter Macej

4,831
22
49

17

You should disclose that you are associated with VSdocman. – Span May 18 '12 at 03:44
1

Not mentioning you are associated with VSdocman removes the credibility of your comment :-/ – Thibaut D. Jul 07 '15 at 08:29

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

5 Answers5