安装工具
doxygen
doxygen-1.8.13-setup.exe
graphviz
graphviz-2.38.msi
Graphviz软件是开源的图形可视化。可视化是图表的结构信息作为表示方式的抽象网络的示图和曲线图。有重要的应用在网络、生物信息学、软件工程、数据库、网页设计、机器学习、视觉界面中的其它技术领域。
htmlhelp
htmlhelp1.3.exe
Doxygen配置方法
打开doxywizard.exe
项目文件:
doxygen 的注释规范
标记的块的详细描述
JavaDoc style,C-style
/**
* ... text ...
*/
Qt style
/*!
* ... text ...
*/
中间*可以省略
/*!
... text ...
*/
至少两个C++注释行,每一行都有一个附加斜线或感叹号
///
/// ... text ...
///
或
//!
//!... text ...
//!
注意这种情况下需要一个单独的空行来结束注释。
多行块注释
/********************************************//**
* ... text
***********************************************/
(note the 2 slashes to end the normal comment block and start a special comment block).
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
简要描述
使用\brief
/*! \brief Brief description.
* Brief description continued.
*
* Detailed description starts here.
*/
JAVADOC_AUTOBRIEF设置为YES,Javadoc风格
/** Brief description which ends at this dot. Details follow
* here.
*/
C++ comments:
/// Brief description which ends at this dot. Details follow
/// here.
用特殊的C++风格的注释
/// Brief description.
/** Detailed description. */
或
//! Brief description.
//! Detailed description
//! starts here.
多个详细的描述
//! Brief description, which is
//! really a detailed description since it spans multiple lines.
/*! Another detailed description!
*/
If you want to document the members of a file, struct, union, class, or enum, it is sometimes desired to place the documentation block after the member instead of before. For this purpose you have to put an additional < marker in the comment block. Note that this also works for the parameters of a function
Qt style
int var; /**< Detailed description after the member */
或
int var; /*!< Detailed description after the member */
或
int var; //!< Detailed description after the member
//!<
或
int var; ///< Detailed description after the member
///<
Most often one only wants to put a brief description after a member
int var; //!< Brief description after the member
或
int var; ///< Brief description after the member
For functions one can use the @param command to document the parameters and then use [in], [out], [in,out] to document the direction. For inline documentation this is also possible by starting with the direction attribute, e.g.
void foo(int v /**< [in] docs for input parameter v. */);
Here is an example of the use of these comment blocks:
*! A test class */
class Afterdoc_Test
{
public:
/** An enum type.
* The documentation block cannot be put after the enum!
*/
enum EnumType
{
int EVal1, /**< enum value 1 */
int EVal2 /**< enum value 2 */
};
void member(); //!< a member function.
protected:
int value; /*!< an integer value */
};
例子:
Qt style
//! A test class.
/*!
A more elaborate class description.
*/
class QTstyle_Test
{
public:
//! An enum.
/*! More detailed enum description. */
enum TEnum {
TVal1, /*!< Enum value TVal1. */
TVal2, /*!< Enum value TVal2. */
TVal3 /*!< Enum value TVal3. */
}
//! Enum pointer.
/*! Details. */
*enumPtr,
//! Enum variable.
/*! Details. */
enumVar;
//! A constructor.
/*!
A more elaborate description of the constructor.
*/
QTstyle_Test();
//! A destructor.
/*!
A more elaborate description of the destructor.
*/
~QTstyle_Test();
//! A normal member taking two arguments and returning an integer value.
/*!
\param a an integer argument.
\param s a constant character pointer.
\return The test results
\sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() and publicVar()
*/
int testMe(int a,const char *s);
//! A pure virtual member.
/*!
\sa testMe()
\param c1 the first argument.
\param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
//! A public variable.
/*!
Details.
*/
int publicVar;
//! A function variable.
/*!
Details.
*/
int (*handler)(int a,int b);
};
JavaDoc style
/**
* A test class. A more elaborate class description.
*/
class Javadoc_Test
{
public:
/**
* An enum.
* More detailed enum description.
*/
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar; /**< enum variable. Details. */
/**
* A constructor.
* A more elaborate description of the constructor.
*/
Javadoc_Test();
/**
* A destructor.
* A more elaborate description of the destructor.
*/
~Javadoc_Test();
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Javadoc_Test()
* @see ~Javadoc_Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
/**
* A pure virtual member.
* @see testMe()
* @param c1 the first argument.
* @param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
/**
* a public variable.
* Details.
*/
int publicVar;
/**
* a function variable.
* Details.
*/
int (*handler)(int a,int b);
};
使用指令时需要在前面加上“\”或者“@”(JavaDoc风格)符号
- \class is used to indicate that the comment block contains documentation for the class
- \struct to document a C-struct.
- \union to document a union.
- \enum to document an enumeration type.
- \fn to document a function.
- \var to document a variable or typedef or enum value.
- \def to document a #define.
- \typedef to document a type definition.
- \file to document a file.
- \namespace to document a namespace.
- \package to document a Java package.
- \interface to document an IDL interface.
Here is an example of a C header named structcmd.h that is documented using structural commands:
/*! \file structcmd.h
\brief A Documented file.
Details.
*/
/*! \def MAX(a,b)
\brief A macro that returns the maximum of \a a and \a b.
Details.
*/
/*! \var typedef unsigned int UINT32
\brief A type definition for a .
Details.
*/
/*! \var int errno
\brief Contains the last error code.
\warning Not thread safe!
*/
/*! \fn int open(const char *pathname,int flags)
\brief Opens a file descriptor.
\param pathname The name of the descriptor.
\param flags Opening flags.
*/
/*! \fn int close(int fd)
\brief Closes the file descriptor \a fd.
\param fd The descriptor to close.
*/
/*! \fn size_t write(int fd,const char *buf, size_t count)
\brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
\param fd The descriptor to write to.
\param buf The data buffer to write.
\param count The number of bytes to write.
*/
/*! \fn int read(int fd,char *buf,size_t count)
\brief Read bytes from a file descriptor.
\param fd The descriptor to read from.
\param buf The buffer to read into.
\param count The number of bytes to read.
*/
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);
文件注释
/**
* @file filename
* @brief This is a brief description.
* @details This is the detail description.
* @author author
* @date date
* @version A001
* @par Copyright (c):
* XXX公司
* @par History:
* version: author, date, desc\n
*/
函数注释
/** 下面是一个含有两个参数的函数的注释说明(简述)
*
* 这里写该函数的详述信息
* @param a 被测试的变量(param描述参数)
* @param s 指向描述测试信息的字符串
* @return 测试结果 (return描述返回值)
* @see Test() (本函数参考其它的相关的函数,这里作一个链接)
* @note (note描述需要注意的问题)
*/
int testMe(int a,const char *s);
数据结构注释
/**
* The brief description.
* The detail description.
*/
typedef struct
{
int var1;///<Description of the member variable
}XXXX;
或者
typedef struct box {
成员变量注释(enum的各个值也如此注释):
double length; ///< The length of the box
double width; ///< The width of the box
double height; ///< The height of the box
};
宏定义注释
/** Description of the macro */
#define XXXX_XXX_XX ox7fffffff
或者
#define XXXX_XXX_XX 0 ///< Description of the macro.
全局和静态变量注释
/** Description of global variable */
int g_xxx = 0;
static int s_xxx = 0; ///< Description of static variable
扩展:
http://www.doxygen.nl/helpers.html
https://www.codeproject.com/Articles/2704/Useful-enhancements-for-Visual-Studio-NET
https://www.atomineerutils.com/products.php
http://doxycomment.sourceforge.net/
参考:
- http://www.stack.nl/~dimitri/doxygen/download.html
- http://www.stack.nl/~dimitri/doxygen/helpers.html
- http://www.graphviz.org/
- http://www.graphviz.org/Download..php
- http://www.cnblogs.com/chenyang920/p/5732643.html
- http://blog.csdn.net/fly542/article/details/7164633
- http://blog.csdn.net/bigpudding24/article/details/45247357
- http://blog.csdn.net/hujian2008/article/details/16343489
- http://blog.csdn.net/wenrenhua08/article/details/39591239
- http://blog.csdn.net/augusdi/article/details/6749845
- https://blog.csdn.net/bigpudding24/article/details/45306351
- https://blog.csdn.net/bigpudding24/article/details/45247357
- Doxygen使用教程
- 用doxygen+graphviz自动化生成代码文档
- 使用Doxygen生成全中文的chm帮助文档