1 / 22

Lab 4: Doxygen Tutorial

Lab 4: Doxygen Tutorial. CS282. 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!.

kreeli
Télécharger la présentation

Lab 4: Doxygen Tutorial

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  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/

More Related