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!

 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!

 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

 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.

 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

 Let’s move our framework over to the CSE server ◦ On the ECC side(all one line):  scp –r YourLabFolder /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 in order to run the above  Congratulations! You’ve created the base directory for your first Doxygen project

 Open up a web browser ◦ Navigate to your Doxygen documentation ◦ CS282_Doxygen/Lab_4/doxygen/html/ 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.

 Finally, let’s take a look at a major project that uses Doxygen documentation  Navigate to ◦ penSceneGraphReferenceDocs/a00026.html penSceneGraphReferenceDocs/a00026.html  Your project will be using Doxygen documentation. Although it will probably have not nearly as many things as OSG does.

 At the beginning of every file, you must have a comment code block like @author, are all tags

 Tags allow your way of telling Doxygen how you want it to document your text specifies that name of your file specifies a brief description of your file specifies the author of the file specifies the date of the file specifies what the function is returning 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.

 For each function, you should have…

 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 @brief ◦ Beginning of each function @return

 When you are finished documenting, copy your source over to the CSE server. (Again, all one line) ◦ scp –r YourLabFolder 2_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.

 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.

 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.

 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

 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 ?)

 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 ◦ CS282_Doxygen/YourProjectNameHere/doxygen/html/ CS282_Doxygen/YourProjectNameHere/doxygen/html/