Using Doxygen with graphviz—the Basics

This Web page provides streamlined instructions to create both html and LaTeX documentation for a basic C or C++ program or package. Thus, this page should be considered a guide to get started with Doxygen. Beyond these instructions, the Doxygen software system provides numerous features for generating software software that allow considerable tailoring of input and output. Overall, learning all options can require much time and effort, but this document can help you get started.

The Basic Steps for Using Doxygen with graphviz

Typically, production of basic documentation with Doxygen follows four steps:

1. preparation of C/C++ files
2. running Doxygen with the C/C++ files as input to produce html and .tex files as output
3. running the LaTeX package on .tex files to create .pdf output
4. adding graphics for calling diagrams, class hierarchies, and file dependencies.

File Preparation

As you write your C/C++ code, follow the the C/C++ Style Guide.

1. Use the file extension ".h" for header files, ".c" for C code, ".cpp" for C++ code, and ".tcc" for C++ template files.

2. To simplify the next steps with Doxygen, place all files for the current project in a separate directory. This directory should contain the .h, .c, .cpp and .tcc files for this software package, but no other files (e.g., no files for other projects). Later steps in these instructions will refer to this directory as the working directory.

   Note: Be sure that the actual file is placed in this directory; Doxygen may lose some functionality, if a symbolic link is in the working directory, rather than the file itself.

3. Use /**, followed by whitespace, at the start of a comment preceding a function, and use */ at the end of the comment.

4. Within a comment (starting with /**),

   • Use @param to identify function parameters, @pre for pre-conditions, and @returns to describe what a function returns.
   • Use @remark to begin a note that should begin on a line by itself.

Although the Doxygen Manual on "Documenting the code" describes many more details that can refine the documentation, the elements listed above likely are adequate to get started.

Running Doxygen

5. Open Doxygen. (On Mac OS X, this may involve using the Finder to click on the Doxygen.app within the Applications section.) When Doxygen opens a window or graphical interface, note several elements of the first screen:

   • The top line contains a space to identify a "working directory".
   • The left panel contains links for "Project", "Mode", "Output", and "Diagrams">
   • The right panel has titles "Wizard", "Expert", and "Run", together with several lines to be completed.

The next steps in these instructions go through these elements step-by-step.

6. Complete the first page on "Project" page in Doxygen's Wizard:

   • The first line on the "Project" page asks, "Specify the working directory from which doxygen will run". Use the "Select" button to navigate to the Working Directory containing the program(s) for this project from Step 2.
   • The first blanks on the right ask for the "Project Name" and "Project synopsis". These two lines will form the title and opening description of the documentation to be produced.
   • The Project version and logo are optional fields—fill in these blanks, or not, as you wish.
   • Although Doxygen allows flexibility in the location of the source code and the placement of the document, in basic programming the "working directory" can be used for both the "Source code directory" and the "Destination directory". (If not set explicitly, these may default to the "working directory".)
   • Once these fields for the "Project" screen are completed, use the "next" button to continue.

7. Doxygen's next page clarifies the "Mode" for generating document.

   • In the top section, the default, "Documented entities only", often can be used
     • However, if the resulting documentation does not show function information, change this setting to "All Entries"!
   • In the bottom section, check the optimization option for the language used in your program(s) (either C++ or C/PHP).
   • Once these fields for the "Mode" screen are completed, use the "next" button to continue.

8. The next page identifies the type of output desired.

   • Typically, the defaults for both "plain HTML" and "LaTeX" can be accepted.
   • After specifying the "Output" screen, click "next" to continue.

9. The next page may identify the type of "diagrams to generate", although doxygen sometimes may skip this step.

   • Typically, the defaults can be accepted.
   • After specifying the "Diagrams" screen, click "next" to continue.

10. The "Run" screen appears next.

    • Click "Run doxygen". Doxygen will print progress notifications in the designated box.
      • If the "run doxygen" button is grayed out, use the "File" at the top of the screen, and use the "save as" option to save a file called "Doxygen" to the working directory.
      • If the "run doxygen" button is active, click it, and review the progress box. If you find an "Error" that a configuration file was not found, run doxygen again.
    • When completed, a note, "***Doxygen has finished" appears.
      • When no errors appear in the progress box and many lines appear saying "Generating ...", the documentation has been produced, and you can check your working directory for both html and LaTeX directories.
      • Within the html directory, clicking on "index.html" should display the documented program on your screen.

Generating a pdf file

Doxygen normally generates a directory labeled "latex", which contains numerous files in LaTeX format. These instructions assume that you have installed the LaTeX package for mathematical typesetting. If not, several free versions are available—try a Web search for "laTeX" and your type of computer (e.g., "latex Mac OS X" identifies the TexShop package that is widely available without cost).

11. In a terminal window, go the "latex" directory, and check the file "refman.tex" is present. This is a "LaTeX" file, used by the LaTeX documentation system (a widely-used package designed for mathematical typesetting).

12. Typing in the "latex" directory within the terminal window, generate a .pdf document with the command:

          make
        

    The pdf document "refman.pdf" should contain the full documentation.

Adding graphics for calling diagrams, class hierarchies, and file dependencies

Using the Doxygen, the fourth step using the wizard involves Diagrams. Within the "Diagrams" section,

• Click the option for "Use Dot tool from the GraphViz package Dot graphs to generate". This will selected several graph options.
• In addition, click the options "Call graphs" and "Called by graphs".

At this point, all graphical options will be set.

With this option, moving to the "Run" tab allows one to click "Run doxygen" as before.

13. If this process runs smoothly, with no error reported, then the full documentation is ready, and nothing more need be done.

14. If "Run doxygen" generates an error to the effect, "dot not found", the underlying issue often is that doxygen cannot find the graphviz package, even if graphviz is installed. This issue is resolved as follows:

    • Within Doxygen, move to the "File" option at the top of the page and select "Save". This saves a configuration file (called Doxygen)) in the directory used for your programs/project.
    • Within a terminal window, use the following command to determine where the "dot" program is located:

                whereis dot
              

      (On my machine, this is "/usr/local/bin/dot", and another possibility might be "/usr/bin/dot". Still other possibilities may be encountered—note whatever location is reported.) If no entry is displayed, you may need to reinstall graphviz!.
    • Use an editor to open that Doxygen file.
      • Search for the line

        DOT_PATH   =
                    

        and insert the location where dot is located, such as

        DOT_PATH               = /usr/local/bin/dot
                    

      • Also check that HAVE_DOT is set to YES:

        HAVE_DOT               = YES
                    

    • After saving the edited file, go back to the file menu of Doxygen, and open the Doxygen file that has just been edited.
    • With this editing complete, try running Doxygen again on your project. With luck, all will proceed smoothly.

Documentation for Further Study

• the Doxygen home page

• an overview of the Doxygen Manual

• Special Commands in Doxygen