1

Doxygen

National University of Kaohsiung Department of Applied Mathematics

Yu-Kai Hong , Chien-Hsiang Liu , Wei-Ren ChangFebruary, 2008

2

Abstract

Source code documentation generator tool,

Doxygen is a documentation system for

C++, C, Java, Objective-C, Python,

IDL (Corba and Microsoft flavors),

Fortran, VHDL, PHP, C#,

and to some extend D.

3

Installation

For Linux, download the software from the web, then you can use it.

For Windows, also download the software, and follow the indication, then you can use it.

Link :http://www.stack.nl/~dimitri/doxygen/

4

Procedure

First, you have to generate a doxygen configuration-file. By using the command: doxygen –g filename

Next, edit your configuration-file and annotations.

Finally, create your doxygen-file. Using the command : doxygen filename

5

Some Doxygen Configurations (1)

PROJECT_NAME: The name of your project. PROJECT_VERSION: The version of your proj

ect. OUTPUT_DIRECTORY: Specify the path to ou

tput your file. INLINE_SOURCES : Decide if you want to e

mbed your codes in the documents .

6

Some Doxygen Configurations (2)

INPUT:

Specify the path to include your file.If you specify a directory, then all files under the directory will been handled.Moreover, you can include multiply files. For example, input=file1.c,file2.c,file3.c .

7

Some Doxygen Configurations (3)

GENERATE_HTML : Decide if you want to generate html-file.

GENERATE_LATEX : Decide if you want to generate LATEX-file.

8

The Comment Form in C++

Single row comment :

// … single row …

Multi-row comment :

/* … row 1 …

… row 2 …

*/

9

The Comment Form in Doxygen

Single column comment :

Type 1 :

/// /// … text …

///

10

The Comment Form in Doxygen

Single column comment :

Type 2 :

//! //! … text …

//!

11

The Comment Form in Doxygen

Example 1:

/// This is the single column comment

void function1(void);

Example 2:

//! This is the single column comment

void function1(void);

Examples\1\index.html

12

The Comment Form in Doxygen

Multi-column comment :

Type 1:

/** * … text …

*/

13

The Comment Form in Doxygen

Multi-column comment :

Type 2 :

/*! * … text …

*/

14

The Comment Form in Doxygen

Multi-column comment :

Type 2 :

/*! … text …

*/

15

The Comment Form in Doxygen

Example 1:

/** This is the multi-column comment\n

* The second column.

*/

double* function2(int*,double);

Examples\2\index.html

16

The Comment Form in Doxygen

Example 2:

/*! This is the multi-column comment\n

* The second column.

*/

double* function2(int*,double);

Examples\2\index.html

17

The Brief and Detail Description

In Front of the program block ” { }”

… Comment …

{

… Program implementation …

}

18

The Brief and Detail Description

Type 1 :

/// brief description. /** detail description. */

19

The Brief and Detail Description

Type 2 :

//! brief description.

//! detail description

//! … text …

20

The Brief and Detail Description

Example 1:

/// This is the brief description.

/** This is the detail description.

*

*/

double function3(double,double);

Examples\3\index.html

21

The Brief and Detail Description

Example 2:

//! This is the brief description.

//! This is the detail description.

//!

//!

double function3(double,double);

Examples\3\index.html

22

The Brief and Detail description

Note1 : Only one brief and detail description are valid.

Note2 : There is one brief description before a

declaration and before a definition of a code

item, only the one before the declaration will

be used.

Note3 : The situation for the detail description is

adverse of the brief description.

23

The Brief and Detail Description

Example :

/// (1)The brief description which is used.

/// (1)The detail description which is not used

double function4(double,double);

/// (2)The brief description which is not used.

/// (2)The detail description which is used.

double function4(double var1,double var2)

{ return (var1+var2); };

Examples\4\index.html

24

The Brief and Detail Description

Behind the program block ” { }”

{

… Program implementation …

}

… Comment …

25

The Brief and Detail Description

Type 1 :

///< brief description. /**< detail description. */

26

The Brief and Detail Description

Type 2 :

//!< brief description

//!< detail description

//!< ... Text ...

27

The Brief and Detail Description

Example 1:

double function5(double,double);

///< This is the brief description.

//!< This is the detail description.

//!<

//!<

Examples\5\index.html

28

The Brief and Detail Description

Example 2:

double function5(double,double);

//!< This is the brief description.

/*!< This is the detail description.

*

*/

Examples\5\index.html

29

The Brief and Detail Description

Note1 : Put additional mark < in the comment block

Note2 : There blocks only used to document functions

and the parameters.

Example :

int var; //!< The single column comment. int var; /**< The multi-column comment. *>

30

The Brief and Detail Description

Note3 : They cannot used to document, files, classes,

unions, structs, namespaces and enums …etc.

Note4 : There is one brief description before a

declaration and before a definition of a code

item, only the one before the declaration will

be used, the same situation is for the detail

description.

31

The Brief and Detail Description

Example :

double function6(double,double);

///< (1)The brief description which is used.

//!< (1)The detail description which is used

double function6(double var1,double var2)

{ return (var1+var2); };

///< (2)The brief description which is not used.

//!< (2)The detail description which is not used.

Examples\6\index.html

32

Special Syntax in Doxygen

Put additional mark \ in the comment block

\ + command

Put the document at other places on the program,

rather than in front of or behind the program block.

33

Some Commands (1) - File

@file: The comment of the file. @author: Informations of the author. @brief:The comment of function or class. Example:    /**

* @file myfile.h * @brief A brief introduction of the file.    *        … complete information …          * @author Some informations of the author. */

34

Some Commands (2) - Function

@param: The comment of the parameter syntax :

@param arg_name comment of arg_name

e.g.@param mtxA Return the Laplacian

matrix called A

35

Some Commands (3) - Function

@return:Display return value. @retval: The comment of return value. Example:

/**

    * @brief A brief introduction of your function

* … complete information …

* @param a Some introduction of parametric a.    * @return Some introduction of return value.  */

36

Some Commands (4)

\b \c \e : set the next word to bold, italic, or courier, respectively. e.g. /// You can make things \b bold, \e italic, or set them in \c courier . results in:  You can make things bold, italic, or set them in courier.

37

Some Commands (4)

\n: force a newline . \internal :

starts a paragraph with "internal information" (such as implementaiton details). The paragraph will be included only if the INTERNAL_DOCS option is enabled.

38

Complete C++ Example

About this code, please refer to

“C++ Language Tutorial, Juan Soulie, 2007.”

1. crectangle.h

2. set_values.h

3. crectangle.cpp

4. This is a complete html file.

39

Reference :

-Home http://www.stack.nl/~dimitri/doxygen/

- Manual http://www.stack.nl/~dimitri/doxygen/manual.html

- Articles http://www.stack.nl/~dimitri/doxygen/articles.html

- Chinese:  http://www.stack.nl/%7Edimitri/doxygen/doxygen_in tro_cn.html