CS 5201: Using Doxygen

This semester, every programming assignment in this class (read: every assignment except the first) must be documented using Doxygen. Doxygen is a tool that takes properly-formatted comments and produces documentation in a variety of formats, including HTML and LaTeX. This documentation is pleasing to the eye, makes working with large libraries less painful, clears up various skin blemishes, and adds years to your life! Furthermore, it provides a bit of structure to commenting, which will help you develop a sense for what you ought to be including in your comments. This example shows what the HTML documentation looks like.

Homework Requirements

Your submission must include a Doxygen configuration file named Doxyfile.
Every class and member function must be documented in a way that Doxygen can understand. I'll be grading your documentation from Doxygen's output.

For advice on writing documentation, see the page on pre- and post-conditions.

Using Doxygen

Doxygen requires a configuration file in order to know how you want your documentation to be generated. Run doxygen -g in your homework directory to generate a default configuration. You should edit this at least a little bit; here's what I changed:

PROJECT_NAME Put a li'l pizzazz in your documentation for heaven's sake!
OUTPUT_DIRECTORY Set this to docs so Doxygen doesn't clutter things up with generated files.
QUIET Set this to YES so Doxygen doesn't get too chatty.
*_AUTOBRIEF This is personal taste, but autobrief is pretty nice.

Also, do not touch the WARNINGS setting! Instead, write docs so that you don't get any warnings in the first place.

Once you've generated a configuration, you'll want to write comments in your source code that Doxygen understands. For the most part, they'll be exactly how you'd write them normally, but with two caveats:

You'll need to use a comment block that Doxygen recognizes as documentation.
You'll need to include commands indicating things like preconditions, postconditions, parameters, return values, and thrown exceptions.

Finally, you'll need to actually generate your documentation. Run doxygen Doxyfile to do so.

See the example code for a good starting point, including a reasonable config file. If you have further questions, see the Doxygen manual or ask your loving TA. (If you don't have a loving TA, you can ask me instead.)