Doxygen 的注释格式

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