Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

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 {...}
like image 577
Dave Avatar asked Aug 31 '11 13:08

Dave


People also ask

What is Doxygen in C?

Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, and to some extent D.

How do you generate documentation from code?

Doxygen is a great tool for generating documentation from source code. The tool is aimed at C++, but it can also be used with PHP, Java, Python, etc. With the help of Doxygen, you can create online HTML documentation. It can also be used to generate output in multiple formats, including Unix man pages, PostScript, etc.

Does doxygen work with C#?

First, assure that your programming/hardware description language has a reasonable chance of being recognized by doxygen. These programming languages are supported by default: C, C++, Lex, C#, Objective-C, IDL, Java, PHP, Python, Fortran and D. Doxygen also supports the hardware description language VHDL by default.


1 Answers

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.

like image 192
Dave Avatar answered Sep 18 '22 10:09

Dave