Doxygen 的注释格式
Doxygen 的注释格式十分灵活.可以是JavaDoc, Qt和仿c++风格, 并且可以混合使用. 如果你熟悉Doc++,就按照你以前的风格写好了:). 下面对每种风格简单举例:
-- JavaDoc风格:
/**
* your comment text.
*/
-- Qt风格:
/*!
* your comment text.
*/
-- 仿c++风格:
/// //!
/// your comment text. 或者: //! your comment text.
/// //!
因为我一直喜欢用c++的单行注释风格(即'//'),所以下面举例就以仿c++风格为例. 下面注释中的'@'和'/'等价,可以根据爱好选用.
因为是在头文件中定义接口,所以注释也就主要集中于头文件中. 如果你想在实现文件中注释,其效果和在头文件中是一样的.下面就举一个实例.
备注:a) '#' 后面的注释是我加的简单解释.不属于文档注释内容.
b) Doxygen 允许一条简短注释,加上一条详细注释.其格式也是多样的. 一般,在 JAVADOC_AUTOBRIEF = NO时,简短注释(///@brief )后空一行,然后再是详细注释. 当 JAVADOC_AUTOBRIEF = YES时,并且简短注释以第一个句号结束,句号后跟一空格(即'. ');或者是新起一行,就可以写详细注释了.示例如下:
# 简短注释. 详细注释.
/// Brief description which ends at this dot. Details follow
/// here.
c) 如果同一代码条目在声明和定义处都有简短注释和详细注释, 则文档只采用声明前的简短注释和定义前的详细注释.
d) 如果是在行尾注释变量,参数等,在你选用的注释格式后面加上'<', 如: ///<行尾的注释.
----------------------------- Example Begin ---------------------------------
# 文件的注释格式
# 注释文件,格式: ///@file 文件名 文件的简短注释.
///@file socket_c.h head file of class socket_c.
# 文件的详细注释.
///Define the interface of class socket_c.
# 普通注释,不会生成在文档中.
//$Id: socket_c.h 287 2004-06-28 06:20:41Z horin $
# 类的注释,格式: ///@brief 简短注释内容.
///@brief class of server socket.
class socket_c
{
private:
public:
# 函数的注释格式
# 函数的注释,格式: ///@brief 函数的简短注释.
///@brief handle the connections of clients.
# 参数注释,格式: ///@param 参数的简短注释.
///@param server the server ip address.
///@param serv_port the server #port.
# 返回值注释,格式: ///@return 返回值的简短注释.
///@return connected socketfd.
# 具体返回值的注释,格式: ///@retval 返回值 该返回值的注释.
///@retval connfd on success.
///@retval 0 on EINTR - system call.
///@retval -1 on error.
# 参见...,格式: ///@see 参见的类/文件等.
///@see main_ppc.cpp
int accept_client(const int listenfd);
};
# 自定义类型的注释
///@brief structure of child process.
struct child_proc_s
{
# 行尾的注释,格式: ///< 注释内容.
pid_t child_pid; ///<child process id.
int child_pipefd; ///<parent's stream pipe to/from child.
};
# 全局变量的注释,也可以采用上面的行尾格式进行注释.
///gloable variable for signal.
pid_t g_pid = 0;
----------------------------- Example End ---------------------------------
转自http://hi.baidu.com/seest/blog/item/efb5264cd21a4dfad72afc02.html