Lab 4: Doxygen Tutorial

CS282

Doxygen is a documentation generator for◦ C++, C, C#, Java, Objective-C, Python, PHP, …

Doxygen will document your code according to the “tags” you specify

It can also document things that you haven’t really documented yet!

What is Doxygen?

You specify options in a configuration file◦ This file is generated by running doxygen, and is

fairly well commented.

Then, inside your source code, you specify “tags” (keywords) which tells Doxygen what kind of documentation you are doing

Finally, you run doxygen, and your html files are automatically generated!

How does it work?

Creating a Doxygen configuration file◦ Editing options in a Doxygen configuration file

Uploading files to your CSE account

Understanding the structure of Doxygen

Documenting your very own class using◦ Accessing your documentation online◦ Utilizing common and important tags

What’s the plan today?

Example

Let’s Get Started!

Doxygen is already installed on the CSE servers, so we do not have to worry about it◦ If you want to install on your home computers, there are

instructions online (aptitude-get, port, etc.)

First of all, let’s download this week’s framework (available on the class site)◦ It is basically last week’s completed version, with an

additional class.

Example 1: Preparing for Doxygen

Since the ECC does not have Doxygen, we will need to work on the CSE servers.

Log onto your CSE account◦ cd ~/public_html◦ Create a directory called “CS282_Doxygen”

This time we have provided you a configuration file inside the framework called “doxyfile”◦ This configuration file allows you to specify options

and tell Doxygen how you want it to format things

Exercise 1 (cont’d)

Let’s move our framework over to the CSE server◦ On the ECC side(all one line):

scp –r YourLabFolder username@cse.unr.edu:/cs/username/public_html/CS282_Doxygen/Lab_4

Now on the CSE side…◦ Go into ~/CS282_Doxygen/Lab_4◦ run the command “doxygen doxyfile”◦ This creates a folder called “doxygen” inside◦ In order to give Doxygen access to all the packages it needs, you

may need to log into YourUserName@banyan.cse.unr.edu in order to run the above command

Congratulations! You’ve created the base directory for your first Doxygen project

Exercise 1 (end)

Let’s Explore

Open up a web browser◦ Navigate to your Doxygen documentation◦ http://www.cse.unr.edu/~YourUserNameHere/

CS282_Doxygen/Lab_4/doxygen/html/ Take a look around

◦ In particular, navigate to the clock class and examine it. (under the classes tab)

◦ Also, look at rigid_body.h (under files tab) Notice the dependency graph

Notice the difference in its documentation compared to the other classes.

Exercise 2: Exploring Doxygen

Finally, let’s take a look at a major project that uses Doxygen documentation

Navigate to◦ http://www.openscenegraph.org/documentation/O

penSceneGraphReferenceDocs/a00026.html

Your project will be using Doxygen documentation. Although it will probably have not nearly as many things as OSG does.

Exercise 2 (end)

At the beginning of every file, you must have a comment code block like so…

@file, @brief, @author, and @date are all tags

Beginning of File

Tags allow your way of telling Doxygen how you want it to document your text◦ @file specifies that name of your file◦ @brief specifies a brief description of your file◦ @author specifies the author of the file◦ @date specifies the date of the file◦ @return specifies what the function is returning◦ @param specifies the parameters of a function

can be chained (i.e. line after line) for multiple param. There are many others, but these are most

of the ones we will focus on for today.

What are tags?

For each function, you should have…

Beginning of Each Function

Document the rigid_body class(On the ECC computer)◦ (ignore the vector class for now)

First, delete the source code in the CSE server◦ rm –rf ~/public_html/CS282_Doxygen/Lab_4

Please document the following using the tags specified below (at the very least)◦ Beginning of the file (.cpp only)

@file, @author, @brief◦ Beginning of each function

Description, @brief, @param, @return

Exercise 3: Using Doxygen

When you are finished documenting, copy your source over to the CSE server. (Again, all one line)◦ scp –r YourLabFolder

username@cse.unr.edu:/cs/username/public_html/CS282_Doxygen/Lab_4

Run doxygen on this folder inside CSE◦ doxygen doxyfile (assuming you’re in your source)

Call me over when you’re done and it is on your website, or if you need help with anything.

Exercise 3 (end)

Unfortunately, because the ECC does not have Doxygen (yet), we have to do this copying between our local and remote hosts.

If you have doxygen installed on your local host, you would only have to run doxygen on the local host and then copy your html folder into your web server’s public_html

And thus avoid moving your source code over as well.

Notes

Let’s examine inline documentation now◦ Example:

int example_number; ///< An integer number◦ Or,

/* This is also an inline example */◦ When using inline doc, be careful its placement◦ There are many other ways to document inline – if

you are interested, Google awaits!

Now let’s document rigid_body.h using inline documentation.

Exercise 4: Details

Once you are finished document rigid_body.h◦ Take a look at sphere.h

You will notice it inherits from rigid_body ◦ This relationship is detected by Doxygen◦ It is visually represented (if the flag is set in the

configuration file) as a graph of dependencies

Copy your code over to the CSE server and run Doxygen (like in the last 2 exercises, don’t forget to delete), and show me the final result

Exercise 4 (end)

1) Create a doxygen configuration file◦ Go to your source code directory, and type in

doxygen –g doxyfile

2) Edit the configuration file options◦ Heavily commented, so you can look through it at your

own discretion. Common tags to edit are: EXTRACT_ALL = YES (around line 301) INLINE_SOURCE = YES (around line 705) HAVE_DOT = YES (around line 1463) CALL_GRAPH = YES (around line 1546) GENERATE_LATEX = NO (around line ?)

General Usage

3) Document your code with Doxygen tags

4) Run the command “doxygen doxyfile”◦ This will create a folder called “html” in your source directory

(or wherever you put your config file)

5) Copy this doxygen folder into your CSE account’s (or your webserver if you have one) “public_html/CS282_Doxygen/[project_name]” folder

6) Access your documentation online◦ http://www.cse.unr.edu/~YourUserNameHere/

CS282_Doxygen/YourProjectNameHere/doxygen/html/

General Usage Part 2