Intro to doxygen
| Back to cs180 |
At this point it should be fairly well drilled into you that good documentation is extremely important. However, very few of us have the patience to document our code like we actually should. doxygen is a program that will automatically generate very nice looking documentation for you, and all you have to do is add a few key words and characters to the comments which should already exist in your code.
If you want to learn how to be an expert at using doxygen, follow the link and learn for yourself. If you want a small tutorial that shows you some of the highlights, follow the following instructions.
Getting Started |
| 1. In your home directory, create a directory called "triangle". Within that directory, create another directory called "docs". |
| 2. Download the following tarball triangle.tgz, and place it in the "triangle" directory. |
| 3. Unpack the tarball > tar -xzvf triangle.tgz You should now have two .cpp files, a .h file and a makefile. It's a silly program that draws a triangle. |
| 4. Look at the files and notice that they look pretty standard, except for a few special characters in the comments. |
| 5. Create a configuration file by typing the following: > doxygen -g my_config |
| 6. Set up some parameters in your configuration file. Open the file "my_config" with your favorite editor. Find the tag "OUTPUT_DIRECTORY" and assign it to your docs directory. (ie. OUTPUT_DIRECTORY = ./docs) Set the "INPUT" tag to the triangle directory and set the "FILE_PATTERNS" tag to use the patterns *.cpp and *.h (these should be space separated). |
| 7. Now lets generate some documentation! At the command prompt in the triangle directory type: > doxygen my_config |
| 8. Now in the docs folder you will find the documentation in various formats. Go to the html directory and open the file index.html with your favorite browser. |
| 9. Notice that only the .h file seems to be documented. Try changing the tags "EXTRACT_ALL" and "EXTRACT_PRIVATE" in your configuration file and see how this effects the documentation. |
| 10. The manual for doxygen can be found at http://www.doxygen.org. Browse the Getting Started section to see how to comment your code for use with doxygen. |
| 11. Try writing a simple program that can be documented using doxygen. There's no need to make the program functional, but try to include a class with a few methods and member variables and possibly a stand alone function, struct, or enumerated type. |