Doxygen intro

From NA-Wiki

Jump to: navigation, search

Doxygen is a tool for generating documentation for source code, primarily designed for C++. It creates nicely formatted pages that describe the components of the code, including graphical representations of class hierarchies and call trees. You can find examples of what Doxygen produces here or here. These documents are generated directly from the source code, and the documentation information is embedded in the source code as specially formatted comments. The nice thing with Doxygen is that it does this without making the comments unreadable in the code.

Visit the official homepage!

Contents

Installing

The Ubuntu package is called doxygen. To generate dependency graphs you will need to install Graphviz (also an Ubuntu package).

Links

  • Official homepage!
  • Official manual, including a "Getting started" section.

Quick getting started

Refer to the manual!

Generate a Doxyfile

The doxyfile is akin to a makefile -- it describes how doxygen should build the documentation. You get a typical doxyfile in the current directory by doing

> doxygen -g

Some first changes to the doxyfile

  • PROJECT_NAME
  • OUTPUT_DIRECTORY. You may specify a absolute or relative path. I.e OUTPUT_DIRECTORY = doc will put the generated files in a subdirectory ./doc
  • JAVADOC_AUTOBRIEF (see below)
  • EXTRACT_ALL. Forces Doxygen to generate documentation for all entities in the code. This is useful for internal documentation (i.e. that is to be used by the developer himself), since it creates a full overview of the project. It does not help a user.
  • HAVE_DOT. This is set to YES to indicate that Graphviz is present in the system (for creating dependency graphs)

Build the documentation

In the directory where the Doxyfile is located (usually the root directory of the project)

> doxygen

That's it! The output can be viewed with a web browser.

Some special comments

Doxygen works by parsing specially formatted comments that precede sections of code. The general structure of these are

/// Line-ended comment with one extra slash

or

/** Multi-line comments 
 * with an extra *
 */

Doxygen provides for giving both brief and detailed descriptions of functions. These appear separately in the documentation. Consult the manual for the details of how to do this. Here we present one convenient way (which is inspired by the behaviour of Javadoc).

If JAVADOC_AUTOBRIEF is set to YES, then Doxygen will interpret the first sentence in a special comment as the brief description, and the rest as detailed. E.g:

/** This is a brief of foo(). 
 * This is a detailed description. foo() takes
 * some data and computes something.
 */
double foo(double *data){

}

Put these special comments in front of classes, structs, enums, functions, variables, macros etc. There are some special keywords that can be inserted that adds specific information to the output. This example adds date and author name

/** Foo is a generic foo object.
 * Used as a base class for Bar
 *
 * \author John Doe
 * \date 2007-12-01
 */
class Foo{

};
Personal tools