pintos-doxygen

Pintos code documentation generated by Doxygen.

The result is stored in the html folder. View it here.

Requirements

You need to have doxygen installed. In addition, the dot tool from graphviz is used to generate call graphs. You can download the graphviz toolkit from http://www.graphviz.org. If you don't want to generate the call graphs, you can disable it in the Doxyfile by setting HAVE_DOT to NO and CALL_GRAPH to NO.

Usage

Copy the Doxyfile file to your pintos source root. Then execute doxygen in the source root.

Note that the original comments in pintos codebase does not conform to the Doxygen code comment format. You need to slightly change the comments:

1. For the struct or function description comments, add an extra * to the beginning. For example, the pintos_init function in threads/init.c is commented with /* Pintos main entry point. */, change it to /** Pintos main entry point. */
2. For the member comments, in addition to adding an extra * to the beginning, add an extra < that follows the second *. For example, the devices/block.c has a struct block with a member comment /* Element in all_blocks. */, change it to /**< Element in all_blocks. */.

Since most of the comments in the pintos codebase are written in a consistent style, we provide a convert_doxygen_comments.py automatically does the above conversions.

Convert one source file:

python convert_doxygen_comments.py /path/to/pintos/src/threads/init.c

Or convert the entire source tree:

python convert_doxygen_comments.py /path/to/pintos/src

The above commands only convert and print the converted result to the console. To be used by doxygen, the replacement has to be written to the file. Pass the --in_place flag to the command will write the result to the original file.

NOTE: the in_place flag will modify the source files. Make sure you don't have outstanding changes so you can easily revert the modifications with git checkout src. In addition, the command should only be applied once. If you invoke it multiple times, the original comment like /* comment */ will become `

After you converted the comments, re-execute the doxygen command. You should see a doxy/html folder in your pintos source root.

In the future, when you make changes to the codebase, you may want to keep the documentation up to date. To do that, you should follow the Doxygen code comment format. In this way, you don't need to convert the comments any more.