Doxygen installation and basics
2015.05.05.
Introduction
Since installing and using Doxygen turned out to be a non-trivial task, I've written a short summary of what installations and settings worked for me. As always with these things, your mileage will vary. The instructions here have worked on both of my Windows 8.1 machines.
(Please forgive my excessive use of parentheses in this post.)
Installation
The adventure starts with installing Doxygen (for obvious reasons), MiKTeX (for generating pdf files), and finally GraphViz (for prettier charts than Doxygen can draw by default, this is optional though).
You can find direct download links below, if you wanna take the easy way for installation, but the download pages where you can get the latest versions (recommended) are also down below.
Initial setup
After installing all those (I just chose the default install directories, but it should work fine with custom install directories too), you have to add a couple paths to your System Environmental Variables in Windows (only editing your user variables could work too, but this is what worked for me), this will make the executables in these folders available from any command prompt open.
You can get to the settings pane for this in one of two ways:
- Either hit Windows+Pause/Break to get to the System window, then go to Advanced system settings in the menu on the left, then click Environment Variables
- Or search for "Edit the system environment variables" in the start menu (worked for me in Windows 8.1)
Scroll down to the "Path" variable, and click Edit.
Add "C:\Program Files (x86)\Graphviz2.38\bin;C:\Program Files (x86)\MiKTeX 2.9\miktex\bin;" to the beginning of the line, make sure each path entry in here is separated properly by semicolons.
Don't copy paste the paths from here, check where you installed the above programs. The GraphViz folder should have "dot.exe" in it, while the MiKTeX one should have "latex.exe" in it.
Settings and basic use
After installation, you can start Doxywizard from the start menu. The GUI is fairly self-explanatory, but here are just some of my notes for using it.
- Your settings for your project will be saved in a file called "Doxyfile", which you can reopen with this same GUI the next time you generate documentation. All the settings you've tinkered around with will be saved in this file.
- It wasn't perfectly clear what the working directory setting was for, but it works fine with it set to the project folder.
- If you have files in your source code directory that you don't need to create documentation for (e.g. memtrace files), you can exclude them from by going to the Expert tab, selecting Input on the left, and then adding the paths to the superfluous files.
- Under Output, I've selected HTML with navigation panel, but that's completely up to personal preference. Make sure you have LaTeX selected as an output format though (hyperlinked PDF setting works well for me).
- Under diagrams, select either the built-in generator, or GraphViz, if you chose to install it.
- Finally, refer to the documentation, and more precisely, the commands page in it.
As weird as it sounds, you can just play around with the settings. Experiment. Doxygen is a powerful tool, and it can do a lot of cool (and lot of unnecessary) things. It has the potential to make your documenting process infinitely easier.
After hitting the Run doxygen button under the Run tab, you should end up with two folders, html and latex, in the destination directory you've selected. You can browse the html version by opening the index.html file found in the html directory. To generate a pdf, open the latex directory, open a command prompt there (I do this by shift-right clicking inside the folder), and run the "make pdf" command. If you have everything set up properly, a "refman.pdf" file should appear, containing your documentation.
An example with some of the basics
/**
* @class Test
* @brief this is a class to show off doxygen comment types
*/
class Test {
int variable; //!< this is a variable
unsigned long otherVariable; //!< and this is another one
public:
/**
* @brief ctor, initializes the variable
* @param x - the value to set the variable to
*/
Test(int x) : variable(x) {};
/** @brief dtor, does nothing */
~Test() {};
/**
* @brief a test function
* @param a - explaination of this variable
* @param s - explaination of this other variable
* @return informatoin about the return value
*/
int testFunction(int a, const char* s) {
std::cout << s;
a++;
return a;
}
/**
* @brief a pure virtual function
*/
virtual void testFunction() = 0;
};
You can check out the documentation generated from this example here.