标签：ble   width   ret   gcc   shell   分支   多参数   col   lin   

前言

大多数程序员讨厌的两件事，一是为代码写注， 二是维护代码文档。doxygen就能把遵守某种格式的注释自动转化为对应的文档， 从而提高程序员的工作效率。

Doxygen是基于GPL的开源项目，是一个非常优秀的文档系统，当前支持在大多数unix（包括linux），windows家族，Mac系统上运行，完全支持C++, C, Java, IDL（Corba和Microsoft 家族）语言，部分支持PHP和C#语言，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。有很多开源项目（如log4cpp和CppUnit）都使用了doxygen文档系统。

安装

• 安装doxygen

sudo apt-get install doxygen

安装后可以使用命令行操作doxygen工具。

• 安装doxygen-gui

sudo apt-get install doxygen-gui

安装后可以通过指令doxywizard打开doxygen图形界面。

• 安装Graphviz

sudo apt-get install graphviz

安装后可以生成文件可视化图。

参数配置

doxygen的参数配置有两种方式， 一种是命令行方式，另一种是图形界面方式。对于第一次使用，推荐使用第二种方式设置好参数，设置好后保存参数文件供下次使用，以后只用手动修改少量设置即可使用。

命令行

一种是通过命令行生成配置文件，然后手动修改文件中的参数。

doxygen -g <doxygen-file> //生成doxygen配置文件
doxygen <doxygen-file> // 根据doxygen配置文件生成文档

图形界面

另一种是通过图形界面修改配置

• 设置Project

注： 设置好了doxygen工作目录后，源文件的目录和生成文档的存放目录请设置为工作目录的相对路径。

• 设置Mode

• 设置Output

• 设置Diagrams

• 生成文档

更多参数

在上述界面中点击Expert按钮，或者用文本方式打开Doxyfile文件，可以看到Doxygen的参数配置项特别多，各个参数的含义其实也并不难掌握，在Doxygen的帮助手册中有详细的介绍，下面我介绍一些常用的参数含义，其余的参数大多可以设置为默认值。

上面的表格只是描述了一些常用的配置，需要更加详细的信息请参考Doxygen的帮助手册。

注释风格

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

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

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

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

• 文件头（包括.h和.cpp）：主要用于声明版权，描述本文件实现的功能，以及文件版本信息等
• 类的定义：主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述
• 类的成员变量定义：在类的成员变量上方，对该成员变量进行简要地描述
• 类的成员函数定义：在类定义的成员函数上方，对该成员函数功能进行简要描述
• 函数的实现：在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等

常用指令

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

注释示例

文件头注释

/**

* @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

*/

类定义注释

/**    本类的功能：打印错误信息  
 *   
 *     本类是一个单件  
 *     在程序中需要进行错误信息打印的地方  
 */ 
class CPrintError  
{  
            ……  
} 

类成员变量定义注释

（1）在成员变量上面加注释的格式

/** 成员变量描述 */ 
int  m_Var; 

（2）在成员变量后面加注释的格式

int  m_color;     /**< 颜色变量 */     

成员函数的注释

/** 下面是一个含有两个参数的函数的注释说明（简述）   *   *     这里写该函数的详述信息   *     @param a 被测试的变量（param描述参数）   *     @param s 指向描述测试信息的字符串   *     @return    测试结果 （return描述返回值）   *     @see    Test()    （本函数参考其它的相关的函数，这里作一个链接）   *     @note    (note描述需要注意的问题)   */ int testMe(int a,const char *s); 

枚举变量的注释

/**    颜色的枚举定义    *     *    该枚举定义了系统中需要用到的颜色\n    *    可以使用该枚举作为系统中颜色的标识    */ enum TEnum   {        RED,           /**< 枚举，标识红色    */           BLUE,          /**< 枚举，标志蓝色    */           YELLOW         /**< 枚举，标志×××. */      }enumVar;      

vscode插件

vscode中有一款Doxygen Documentation Generator插件，可以快速补全doxygen的注释。

参考

• doxygen官网

• Doxygen详细介绍

doxygen的安装与使用

标签：ble   width   ret   gcc   shell   分支   多参数   col   lin   

原文地址：https://www.cnblogs.com/ChrisCoder/p/14924174.html