码迷,mamicode.com
首页 > 其他好文 > 详细

doxygen的安装与使用

时间:2021-06-24 17:40:54      阅读:0      评论:0      收藏:0      [点我收藏+]

标签: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的帮助手册中有详细的介绍,下面我介绍一些常用的参数含义,其余的参数大多可以设置为默认值。

参数 解释
DOXYFILE_ENCODING Doxygen文件的编码方式,默认为UTF-8,若希望支持中文,最好设置为 GB2312
PROJECT_NAME Project 的名字,以一个单词为主,多个单词请使用双引号括住。
PROJECT_VERSION Project的版本号码。
OUTPUT_DIRECTORY 输出路径。产生的文件会放在这个路径之下。如果没有填这个路径,将会以目前所在路径作为输出路径。
OUTPUT_LANGUAGE 输出语言, 默认为English 。
EXTRACT_ALL 为NO,只解释有doxygen格式注释的代码;为YES,解析所有代码,即使没有注释
EXTRACT_PRIVATE 是否解析类的私有成员
EXTRACT_STATIC 是否解析静态项
EXTRACT_LOCAL_CLASSES 是否解析源文件(cpp文件)中定义的类
INPUT 指定加载或找寻要处理的程序代码文件路径。这边是一个表列式的型态。并且可指定档案及路径。
FILE_PATTERNS 如果您的INPUT Tag 中指定了目录。您可以透过这个Tag来要求Doxygen在处理时,只针对特定的档案进行动作。例如:您希望对目录下的扩展名为.c, .cpp及.h的档案作处理。您可设定FILE_PATTERNS = *.c, *.cpp, *.h。
RECURSIVE 这是一个布尔值的Tag,只接受YES或NO。当设定为YES时,INPUT所指定目录的所有子目录都会被处理.
EXCLUDE 如果您有某几个特定档案或是目录,不希望经过Doxygen处理。您可在这个Tag中指定。
EXCLUDE_PATTERNS 类似于FILE_PATTERNS的用法,只是这个Tag是供EXCLUDE所使用。
SOURCE_BROWSER 如果设定为YES,则Doxygen会产生出源文件的列表,以供查阅。
INLINE_SOURCES 如果设定为YES ,则函数和类的实现代码被包含在文档中
ALPHABETICAL_INDEX 如果设定为YES,则一个依照字母排序的列表会加入在产生的文件中。(有很多类、结构等项时建议设为YES)
GENERATE_HTML 若设定为YES ,就会产生HTML版本的说明文件。HTML文件是Doxygen预设产生的格式之一。
HTML_OUTPUT HTML文件的输出目录。这是一个相对路径,所以实际的路径为OUTPUT_DIRECTORY加上HTML_OUTPUT。这个设定预设为html。
GENERATE_HTMLHELP 是否生成压缩HTML格式文档(.chm)
HTML_FILE_EXTENSION HTML文件的扩展名。预设为.html。
HTML_HEADER 要使用在每一页HTML文件中的Header。如果没有指定,Doxygen会使用自己预设的Header。
HTML_FOOTER 要使用在每一页HTML文件中的Footer。如果没有指定,Doxygen会使用自己预设的Footer。
HTML_STYLESHEET 您可给定一个CSS 的设定,让HTML的输出结果更完美。
GENERATE_HTMLHELP 如设定为YES,Doxygen会产生一个索引文件。这个索引文件在您需要制作windows 上的HTML格式的HELP档案时会用的上。
GENERATE_TREEVIEW 若设定为YES,Doxygen会帮您产生一个树状结构,在画面左侧。这个树状结构是以JavaScript所写成。所以需要新版的Browser才能正确显示。
TREEVIEW_WIDTH 用来设定树状结构在画面上的宽度。
GENERATE_LATEX 设定为YES 时,会产生LaTeX 的文件。不过您的系统必需要有安装LaTeX 的相关工具。
LATEX_OUTPUT LaTeX文件的输出目录,与HTML_OUTPUT用法相同,一样是指在OUTPUT_DIRECTORY之下的路径。预设为latex。
LATEX_CMD_NAME LaTeX程序的命令名称及档案所在。预设为latex。
GENERATE_RTF 若设定为YES ,则会产生RTF 格式的说明档。
RTF_OUTPUT 与HTML_OUTPUT 用法相同,用来指定RTF 输出档案路径。预设为rtf。
GENERATE_MAN 若设定为YES ,则会产生Unix Man Page 格式的说明文件。
MAN_OUTPUT 与HTML_OUTPUT 用法相同,用来指定Man Page的输出目录。预设为man。
GENERATE_XML 若设定为YES ,则会产生XML 格式的说明文件。
ENABLE_PREPROCESSING 若设定为YES ,则Doxygen 会激活C 的前置处理器来处理原始档。
PREDEFINED 可以让您自行定义一些宏。类似于gcc 中的-D选项。
CLASS_DIAGRAMS 这个标记用来生成类继承层次结构图。要想生成更好的视图,可以从 Graphviz 下载站点 下载 dot 工具。Doxyfile 中的以下标记用来生成图表:
HAVE_DOT 如果这个标记设置为 Yes,doxygen 就使用 dot 工具生成更强大的图形,比如帮助理解类成员及其数据结构的协作图。注意,如果这个标记设置为 Yes,<CLASS_DIAGRAMS> 标记就无效了
CLASS_GRAPH 如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes,就使用 dot 生成继承层次结构图
GRAPHICAL_HIERARCHY 设置为YES时,将会绘制一个图形表示的类图结构

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

注释风格

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

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

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

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

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

常用指令

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

@file 档案的批注说明。
@author 作者的信息
@brief 用于class 或function的简易说明eg:@brief ``本函数负责打印错误信息串
@param 主要用于函数说明中,后面接参数的名字,然后再接关于该参数的说明
@return 描述该函数的返回值情况eg:@return 本函数返回执行结果,若成功则返回TRUE,否则返回FLASE
@retval 描述返回值类型eg:@retval NULL ``空字符串。 @retval !NULL ``非空字符串。
@note 注解
@attention 注意
@warning 警告信息
@enum 引用了某个枚举,Doxygen会在该枚举处产生一个链接eg:@enum CTest::MyEnum
@var 引用了某个变量,Doxygen会在该枚举处产生一个链接eg:@var CTest::m_FileKey
@class 引用某个类,格式:@class [] []eg:@class CTest "inc/class.h"
@exception 可能产生的异常描述eg:@exception 本函数执行可能会产生超出范围的异常

注释示例

文件头注释

/**

* @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的安装与使用

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

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

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!