USC CSD Home
 

Doxygen Tutorial - CSCI 102L, Spring 2011, Section 30349R

 
What is Doxygen?
Doxygen is an automatted documentation formatter and generator for C++. It allows you to specially tag comments in your code that will be used to generate nicely formatted output such as HTML.
 
Getting Started
In order to get Doxygen to work, you'll have to do a little bit of setup on your Unix account for aludra/nunki. First of all, execute the following command on the command line to figure out what Unix shell you're using (it will make a difference in what syntax you must use):
    echo $SHELL
Your result should be something like "bash", "csh" or "tcsh". If it's something else weird like "ksh", you're on your own for syntax. Read the appropriate section below for getting things setup with your particular shell.

Setup for "bash"

Open your BASH profile in your favorite text editor (I'll use emacs here):
    emacs ~/.bash_profile
Go down to the bottom of the file and add the following line (MAKE SURE you add a newline after this line or you'll have issues):
    export PATH=${PATH}:~csci102/bin
If you remember our discussion about the PATH environment variable in class, you'll see that this is adding everything in the bin directory in the csci102 account's home directory to your PATH so you can just type "doxygen" instead of having to type "/home/scf-06/csci102/bin/doxygen".

To test your installation you can either log out and log back in or force a reload of your .bash_profile. Note that logging out and logging back in also makes your profile be reloaded. To force Unix to reload your .bash_profile without logging out, type this command:

    source ~/.bash_profile
Now, to test your installation, just type doxygen onto the command line with no arguments and hit enter. If it spews a bunch of documentation, you're good to go. If it gives you an error like "doxygen: Command not found.", you did something wrong.

Setup for "csh/tcsh"

Open your cshrc (pronounced "see-shark") file in your favorite text editor (I'll use emacs here):
    emacs ~/.cshrc
Go down to the bottom of the file and add the following line (MAKE SURE you add a newline after this line or you'll have issues):
    setenv PATH ${PATH}:~csci102/bin
If you remember our discussion about the PATH environment variable in class, you'll see that this is adding everything in the bin directory in the csci102 account's home directory to your PATH so you can just type "doxygen" instead of having to type "/home/scf-06/csci102/bin/doxygen".

To test your installation you can either log out and log back in or force a reload of your .cshrc. Note that logging out and logging back in also makes your .cshrc be reloaded. To force Unix to reload your .cshrc without logging out, type this command:

    source ~/.cshrc
Now, to test your installation, just type doxygen onto the command line with no arguments and hit enter. If it spews a bunch of documentation, you're good to go. If it gives you an error like "doxygen: Command not found.", you did something wrong.
 
Running Doxygen
You can actually run Doxygen without doing any commenting of your code and it will still generate documentation just based on the structure of your code and the relationships between your classes.

Step 1: I highly recommend copying your code into a temporary directory before running doxygen against it. In theory there shouldn't be any problems, but it never hurts to be safe. So go to the directory where your code is and just do something like this to make a temporary directory, copy all your files into it and then move into that directory:

    mkdir tmp
    cp ./* ./tmp
    cd tmp
Step 2: Before you can generate documentation with Doxygen, you need to generate a Doxygen configuration file. To do that, simply type this command (you may choose a different name than "config.txt" if you wish):
    doxygen -g config.txt
This command will generate a configuration file named "config.txt" in the current directory. You are welcome to tweak the values in the configuration if you like, but we will just use the defaults for this tutorial.

Step 3: Once you've generated a configuration file, you're ready to actually generate documentation. The next section will discuss some of the various tags you can use to make Doxygen more meaningful and interesting, but you can generate some base documentation even before you comment. To generate Doxygen documentation, simply do this (in the same directory as your source code and config file):

    doxygen config.txt
By default, this will create two subdirectories in your current directory named "latex" and "html". In the future, you can disable generation of the "latex" directory via the "GENERATE_LATEX" property in the configuration file if you wish, but for now you can just delete the latex directory. The "html" directory is the one that we want to use.
 
Commenting Your Code
Doxygen generates more detailed documentation from your source code by picking out special tags that you place in your comments. We will present just basic special tags here, but if you're curious, you use these links to find more information about Documentation Blocks and special Source Tags. We will present examples here that closely mirror the Java "javadoc" style of documentation since you'll be learning Java in CSCI 200, but Doxygen is very flexible, so follow the links if you're curious about what other types of commenting/documentation styles Doxygen allows.

Commenting Classes

If you want to attach a description to your classes, you simply need to just write a basic description using the special Doxygen comment block notation of /** description */ and place it before the first line of your class. You should also use the /** description */ notation to comment the member variables of your class (though keep in mind private members/functions will not show up on the Doxygen output by default).

Tags of interest:

  • @author name - Specifies the name of the author of the class
An example of commenting a class is shown below:
/**
  A basic class to represent a point somewhere in
  2D space.

  @author Brent Nash
*/
class Point
{
  private:
    
    /** The X coordinate in 2D space */
    int x;
    /** The Y coordinate in 2D space */
    int y;
    
   //The rest of the code here
};

Commenting Functions

If you want to attach a description to your functions, you simply need to just write a basic description using the special Doxygen comment block notation of /** description */ and place it before the first line of your function. If you're commenting member methods of a class, you should Doxygen comment them in the header file and then just put any other implementation specific comments in the implementation file.

Tags of interest:

  • @pre description - What are the preconditions for calling this function?
  • @post description - What are the postconditions resulting from calling this function?
  • @param name description - Specify a description for the input parameter "name"
  • @return description - Describe the return value of this function
  • @throw exception description - Specify that an exception of type "exception" is thrown and explain how/when the throw happens
An example of commenting a function is shown below:
/**
  Factory method for creating shapes. Takes in a string
      representation of a shape and returns a pointer to that
      particular shape.
  Only works for shapes that derive from the Shape object.
  Center points for returned shapes will always be (0,0).
  
  @pre None
  @post Does not change the object
  @param name The name of the shape to generate (e.g. "triangle",
      "rectangle", or "circle").
  Input is case-sensitive.
  @return A pointer to a Shape object dynamically allocated on the
      heap if "name" is a valid, recognized shape type or NULL if
      "name" does not specify the name of a known shape.
*/
Shape* createShape(std::string name);

Commenting Applications

If you want to attach all your high-level design document information to your source code, you can also do that by specifying the mainpage and section tags to your source code in a Doxygen comment block /** description */ like you would for other things. These comments can go into any source file in your project, but they generally go at the top of the file that contains the "int main" method. These comments will appear on the "Main Page" section of the Doxygen HTML output.

Tags of interest:

  • @mainpage page_title - What is the title of this application?
  • @section section_name section_title - Create a section header. Any text underneath this tag will be part of this section.
An example of creating high-level design document commenting is shown below:
/** 

@mainpage CSCI 102 Lecture #9 Factory Class Example
 
@section purpose Purpose/Overview

Describe your purpose/overview here.

@section reqs Requirements

List your requirements here.

@section globals Global Data/Functions

Describe your globals here.

@section objects Objects

Describe your objects here.

@section arch High-level architecture

Describe your high-level architecture here.

@section functions Function Descriptions

Describe your functions here.

@section ui User Interface

Describe your user interface here.

@section testing Test Cases

Describe your test cases here.
*/
 
Making Your Documentation Web Accessible
Step 1: First you must create the root directory of your webpage in your home directory. Execute this command to create the directory:
    mkdir ~/public_html
The "public_html" directory is picked up by USC's webserver. If your USC username is "ttrojan" then your corresponding URL in a web browser will be "http://scf.usc.edu/~ttrojan".

Step 2: You need to copy the documentation that you've generated into your public web directory. Let's assume that you generated your documentation into the directory "~/lab5/tmp/html" (keep in mind "~" is Unix shell shorthand for your home directory). You can just use a basic Unix copy command to put it where it needs to go like this:

    cp -r ~/lab5/tmp/html ~/public_html/lab5
The "-r" argument to "cp" does a recursive copy that will copy the directory and all of the files and subdirectories within it.

Step 3: The final step is to make all the files in your "public_html" directory readable by the rest of the world. In order to do this, execute this command to make your web files readable:

    chmod -R 755 ~/public_html
Once you've completed this step, type your URL into a web browser and it should work. For the example we presented in Step 2, the corresponding URL that you would type into your web browser is "http://scf.usc.edu/~ttrojan/lab5/index.html" (obviously remember to replace "ttrojan" with your username and "lab5" with whatever you named the folder when you did the original copy of the files).
 
Working Example
The code from Lecture 9 of Spring 2010 has been completely documented in the Doxygen style, so if you would like examples of how to document your source files, check out these examples: You can see the corresponding output of the Doxygen process here.
 

[Last updated Sat Sep 19 2020]    [Please see copyright regarding copying.]