1 doxygen national university of kaohsiung department of applied mathematics yu-kai hong,...
TRANSCRIPT
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