Doxygen Tutorial - CSCI 102L, Fall 2011

    echo $SHELL

Setup for "bash"

    emacs ~/.bash_profile

    export PATH=${PATH}:~csci102/bin

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

Setup for "csh/tcsh"

    emacs ~/.cshrc

    setenv PATH ${PATH}:~csci102/bin

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

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

    doxygen -g config.txt

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

Commenting Classes

Tags of interest:

• @author name - Specifies the name of the author of the class

/**
  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

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

/**
  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

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.

/** 

@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.
*/

    mkdir ~/public_html

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

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

• circle.h
• circle.cpp
• main.cpp
• point.h
• point.cpp
• rectangle.h
• rectangle.cpp
• shape.h
• shape.cpp
• shapefactory.h
• shapefactory.cpp
• triangle.h
• triangle.cpp