Automatic Documentation

We use a tool called Doxygen to create automatic documentation from comments in the code. This page is a short introduction on how to use Doxygen for this project. You can find more information in the Doxygen manual.

1 Installation
2 Create the Documentation
3 Edit the Documentation

---

Installation - Linux

1. Download the binaries here.
2. Open a terminal and navigate to the download folder.
3. Unpack the downloaded archive, typing "tar -zxvf <archivename>".
4. Navigate to the newly created folder.
5. Type "./configure".
6. Type "make install".

If this doesn't work or you dont want to use Linux, refer to the installation guide on the Doxygen homepage.

Optional:
If Doxygen is supposed to be able to draw graphs, you will need the graph-toolkit graphviz.In fact, this is used in the OSOLSim documentation and if you dont have graphviz Doxygen might throw an error, unless you disable graphs in the Doxyfile.
Use the Ubuntu Software Center for the installation. If you dont have Ubuntu, view the download page on the graphviz website. The easiest way is probably to scroll down and download the Third-Party Executable Packages.

If you want PDF, Latex or Postscript output, you need a Latex distribution.

---

Create the Documentation

Doxygen automatically creates the documentation parsing the source code for comments conforming to a certain syntax. The output is a fully designed HTML, PDF or Latex (quite some other output formats are possible). So you don't need to give much thought to the formatting or structure of your documentation.

To create the documentation you need a settings file first. There is already one in the repository, named Doxyfile.* Then type "doxygen" on the shell while in the project folder. As of now (2012-12-12) the output is html. To view it, just open the index.html in the newly created folder html in the project directory.

*In the case that for some reason there is no settings file you can create one on your own typing "doxywizard" on the shell and following the wizard.

---

Edit the Documentation

To parse the comments correctly, they should be put directly before the associated element. In the example below the member that is to be documented is the function "foo ()" and the comment is placed right in front. Members that can be documented are classes, functions, methods, structs etc. Comments often include the following:

• A brief description, preceded by @brief, In the documentation you will find lists of all brief description of members of the same category grouped together.
• A more detailed description. There is no @detailed-expression. An empty line separates the brief from the detailed description.
• A todo marker, preceded by @todo. In the documentation you will find it at Related Pages > Todo List.

For functions and methods:

• A short description of every parameter, preceded by @param followed by the exact name of the parameter followed by the description.
• A short description of the return value, preceded by @return.

This looks something like this:

/** @brief Brief description of foo().

    Detailed description of foo().

    @param p1 Short description of p1.
    @param p2 Short description of p2.

    @return Short description of the return value.

    @todo Short todo-note.
*/

int foo(int p1, double p2) {
    ...
}

To document members of a class (like public variables), a struct, a union or an enum you can also put the comments right behind the members:

struct foo {
    int p1; ///< Short description of p1.
    double p2; ///< Short description of p2.
}

Doxygen provides many expressions. Sometimes there are several syntax expressions that all mean the same thing in order to accomodate for different popular commenting styles (like in Javadoc- or Qt-style documentation). But this is not important as long as you dont want to dig deeper. The information in this guide and a short look at some examples in the code and at the corresponding output should suffice to enable you to contribute to the documentation.

Now, whenever you want to make your modifications in the comments visible, just save the file, type "doxygen" on the shell (while in the project directory) and open the index.html or update the file in the browser (hit F5).

To change the settings for the Doxygen-parser, edit the Doxyfile with a text editor. Some things you can specify are...

• ...the output destination
• ...the output format
• ...the presence/absence of a todo- and other lists
• ...the color scheme
• ...many other design aspects