Using doxygen to create documentation for existing C# code with XML comments

Question

I've read everywhere that doxygen is the way to go for generating documentation for C# code. I've got a single interface that I want to document first (baby steps), and it already has the XML comments (///) present.

Because of the vast number of posts and information available (including doxygen.org) that say these comments are already supported, I'm surprised that when I run doxywizard, I get errors like "warning: Compound Company::Product::MyInterface is not documented".

This leads me to believe that I have somehow misunderstood XML documentation (hopefully not, according to MSDN I am talking about the right thing), or I have misconfigured doxywizard.

I first ran doxywizard via the Wizard tab, and specified that I want to support C#/Java. When I run it, my HTML page is blank, presumably because of the previously-mentioned warnings. I then tried specifying a single file via the Expert tab and ran again -- same behavior.

Can anyone tell me what switch or setting I'm missing to get doxygen to generate the HTML?

Here's an example of what a documented property/method looks like in my interface:

/// <summary>
/// Retrieve the version of the device
/// </summary>
String Version { get; }

/// <summary>
/// Does something cool or really cool
/// </summary>
/// <param name="thing">0 = something cool, 1 = something really cool</param>
void DoSomething( Int32 thing);

I do have a comment above the interface, like this:

/// <summary>
/// MyInterface
/// </summary>
public interface MyInterface {...}

Dave, do you have a comment above the line where the interface is declared? — Eric Farr
@Eric yes I do... I have updated my question to show the comment. Perhaps I need some special doxygen syntax there? — Dave
Hmmm.... That all looks fine. All I can think of is that there are a bunch of EXTRACT_ parameters. Try turning them all to YES. What you are trying to do will work. There is just something missing. There is a little more trial-and-error required with doygen that I'd like. — Eric Farr
@Eric haha, good timing! I just posted about that after reading something about EXTRACT_ALL. Enabling that made it work, though I feel it should have worked even with that setting disabled. Thank you for the comments. — Dave

Dave Dave · Accepted Answer · 2011-08-31T13:47:14

I think I've figured it out. The doxygen manual says that EXTRACT_ALL = 0 is the default setting, and in this case "will only generate documentation for documented members, files, classes and namespaces". Now, I thought that I had documented them properly, but apparently not. I just enabled EXTRACT_ALL, and the warnings went away, and I got documentation for my interface! I read up on the "special documentation blocks", thinking I was missing something (thanks to Eric Farr's comment), but it made no mention of doing anything special for C# code, so I am under the assumption that the default value for EXTRACT_ALL should have still worked.

Using doxygen to create documentation for existing C# code with XML comments

1 Answers