Lab 4: Doxygen Tutorial

1. Lab 4: Doxygen Tutorial CS282

2. What is Doxygen? • 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!

3. How does it work? • 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!

4. What’s the plan today? • 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

5. Example

6. Let’s Get Started!

7. Example 1: Preparing for Doxygen • 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.

8. Exercise 1 (cont’d) • 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

9. Exercise 1 (end) • 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 “doxygendoxyfile” • 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

10. Let’s Explore

11. Exercise 2: Exploring Doxygen • 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.

12. Exercise 2 (end) • Finally, let’s take a look at a major project that uses Doxygen documentation • Navigate to • http://www.openscenegraph.org/documentation/OpenSceneGraphReferenceDocs/a00026.html • Your project will be using Doxygen documentation. Although it will probably have not nearly as many things as OSG does.

13. Beginning of File • At the beginning of every file, you must have a comment code block like so… • @file, @brief, @author, and @date are all tags

14. What are tags? • 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.

15. Beginning of Each Function • For each function, you should have…

16. Exercise 3: Using Doxygen • 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

17. Exercise 3 (end) • When you are finished documenting, copy your source over to the CSE server. (Again, all one line) • scp –r YourLabFolderusername@cse.unr.edu:/cs/username/public_html/CS282_Doxygen/Lab_4 • Run doxygen on this folder inside CSE • doxygendoxyfile (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.

18. Notes • 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.

19. Exercise 4: Details • Let’s examine inline documentation now • Example: • intexample_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.

20. Exercise 4 (end) • 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

21. General Usage • 1) Create a doxygen configuration file • Go to your source code directory, and type in • doxygen –gdoxyfile • 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 ?)

22. General Usage Part 2 • 3) Document your code with Doxygen tags • 4) Run the command “doxygendoxyfile” • 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/