Doxygen notes

Marine CARPUAT, TA (COMP151, Spring 2006, Prof. Dekai WU, HKUST)

Make sure you always document your code properly... Not only for COMP151 labs, but for every piece of code you write.

Why document your code?

Comment your code so that someone who has no idea what the code does can understand it. And keep in mind that, one day, that someone will be you!

What are useful comments?

Compare the 2 comments below:

Comment B is useless because it only repeats the code without adding new information. In contrast, comment A provides useful information by explaining the purpose of this particular line of code.

The Javadoc style guide contains a good example of useful vs. useless API description, and other comment writing style tips.

Writing documentation with Doxygen

Doxygen is a documentation system for C++, C, and other programming languages, that automatically generates documentation in both html and LaTeX format, for a set of source files that are documented in a specific format.

Running Doxygen will not only give you a nicely formatted documentation, it will also help keep your documentation complete and consistent.

4 simple steps

  1. Document *ALL* your classes and functions using Doxygen style comments ( see examples below)
  2. Generate a doxygen config file by typing
    doxygen -g doxygen.config
    in the directory where your source files are.
  3. Use pico to edit the doxygen.config file. For instance, you can change the project name (e.g. call it "lab02"), the output directory (e.g. call it "doc"), and other parameters as you see fit.
  4. run doxygen doxygen.config
DONE! you can now open doc/html/index.html to browse the html documentation for your code.

For a more detailed introduction, check out the Doxygen manual

Writing comments for Doxygen

Here is an example of the use of Doxygen comment blocks. A Doxygen documentation block is a C or C++ style comment block with some additional markings, so that Doxygen knows it is a piece of documentation that needs to end up in the generated documentation.

For more details, consult the Doxygen manual section on Documenting the code.

Some Doxygen tips

If you want ALL your comments to appear in the generated Doxygen documentation, including comments in the main function, comments for private members, etc., you should set the following parameters in the config file: