java doxygen_Doxygen 使用总结

转自：http://ticktick.blog.51cto.com/823160/188674

5      Doxygen的注释风格

5.1   综述

在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是brief描述, 另一种就是detailed。 两种都是可选的，但不能同时没有。

顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。

Doxygen支持c风格注释、c++风格注释以及javaDoc风格注释等，下面将分别予以介绍。

若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：

1) 文件头(包括.h和.cpp)

主要用于声明版权，描述本文件实现的功能，以及文件版本信息等

2) 类的定义

主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述

3) 类的成员变量定义

在类的成员变量上方，对该成员变量进行简要地描述

4) 类的成员函数定义

在类定义的成员函数上方，对该成员函数功能进行简要描述

5) 函数的实现在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等

5.2    Doxygen支持的指令

5.2.1   概述

可以在注释中加一些Doxygen支持的指令，主要作用是控制输出文档的排版格式，使用这些指令时需要在前面加上“\”或者“@”(JavaDoc风格)符号，告诉Doxygen这些是一些特殊的指令，通过加入这些指令以及配备相应的文字，可以生成更加丰富的文档，下面对比较常用的指令做一下简单介绍。

5.2.2   常用指令介绍

@file

档案的批注说明。

@author

作者的信息

@brief

用于class 或function的简易说明

eg：

@brief本函数负责打印错误信息串

@param

主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明

@return

描述该函数的返回值情况

eg:

@return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE

@retval

描述返回值类型

eg:

@retval NULL空字符串。

@retval !NULL非空字符串。