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.
Doxygen requires a configuration file in order to know how you want your documentation to be generated.
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_NAMEPut a li'l pizzazz in your documentation for heaven's sake!
OUTPUT_DIRECTORYSet this to
docsso Doxygen doesn't clutter things up with generated files.
QUIETSet this to
YESso Doxygen doesn't get too chatty.
*_AUTOBRIEFThis is personal taste, but autobrief is pretty nice.
WARNINGSsetting! 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:
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.)