Abstract

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


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


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


Single column comment :

Type 2 :

//! //! … text …

//!

11


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


Multi-column comment :

Type 1:

/** * … text …

*/

13



Type 2 :

/*! * … text …

*/

14



Type 2 :

/*! … text …

*/

15


Example 1:

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

* The second column.

*/

double* function2(int*,double);


16


Example 2:

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

* The second column.

*/

double* function2(int*,double);


17

The Brief and Detail Description

In Front of the program block ” { }”

… Comment …

{

… Program implementation …

}

18


Type 1 :

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

19


Type 2 :

//! brief description.

//! detail description

//! … text …

20


Example 1:

/// This is the brief description.

/** This is the detail description.

*

*/

double function3(double,double);


21


Example 2:

//! This is the brief description.

//! This is the detail description.

//!

//!



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


Example :

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

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


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

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

double function4(double var1,double var2)

{ return (var1+var2); };


24


Behind the program block ” { }”

{

… Program implementation …

}

… Comment …

25


Type 1 :

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

26


Type 2 :

//!< brief description

//!< detail description

//!< ... Text ...

27


Example 1:


///< This is the brief description.

//!< This is the detail description.

//!<

//!<


28


Example 2:


//!< This is the brief description.

/*!< This is the detail description.

*

*/


29


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


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


Example :


///< (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.


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

Abstract

Documents

Transcript of Abstract