Doxygen – a brief tutorial

I am using Doxygen to generate simple web-based documentation from my well-documented NExtra project’s source code. Doxygen also supports extracting the documentation in various other formats (HTML, LaTex, .man, XML etc.), but I chose to keep it simple.

To extract a simple HTML site from your documentation, just follow these simple steps:

  1. Download Doxygen and install it.
  2. Run the Doxygen wizard, which opens a small window wit the Wizard tab selected:doxygen_start
  3. Under the Project section, define these properties:
    • Project name (e.g. “.NET Extensions”)
    • Project version or id (e.g. “1.0.0.0”)
    • Source code directory (your source code root)
    • Make sure to check the “Scan recursively” check box
    • Destination dictionary (where you want the documentation to be extracted)
  4. Under the Mode section, select All entities and Optimize for Java or C#
  5. Under the Output section, select the various output formats you want Doxygen to create.
  6. Since you selected All entities, you may believe that all entities will be extracted. Well, sadly, this is not true. For instance, Doxygen will not extract documentation for static classes, unless you explicitly tell it to.
  7. So, select the Expert tab (wow, an expert already, huh?) and make sure that the EXTRACT_STATIC checkbox is checked. If not, you will find that static parts of your application are left out of the documentation. You can also check other boxes to configure Doxygen in detail.
  8. Finally, you are more than ready to select the Run tab and click the “Run Doxygen” button. This will start Doxygen, which will place the documentation in your specified destination folder.

If you think that the documentation is plain and “boring” in HTML format, you can skin it with CSS. I will cover that part in another blog entry.

Advertisements