在VS2103环境中集成Doxygen工具

自己已将学习了两三次了吧,差不多这次该总结一下:

Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,完全支持C、C++、Java、Objective-C和IDL语言,部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始,生成HTML格式的在线类浏览器,或离线的LATEX、RTF参考手册。

Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个纯粹的参考手册,对于后面利用您的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于您来说,就是沉重的负担。Doxygen 就是在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的文档了。因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生文档。

参考的博文有:http://sunzhennian.blog.163.com/blog/static/1951730712011112210184592/

http://blog.csdn.net/flatcd/article/details/138678

http://blog.csdn.net/u012501459/article/details/37668893

http://blog.csdn.net/bigpudding24/article/details/45247357

各有各得点,自己在总结。

使用步骤

1、第一次使用需要安装doxygen的程序

2、生成doxygen配置文件

3、编码时,按照某种格式编写注释
4、生成对应文档

1、安装doxygen及其相关程序

1.1Doxygen下载

http://sourceforge.net/projects/doxygen/?source=dlp 进行下载

本文使用的为Doxygen 1.8.3.1

安装,我们将在配置的时候使用doxywizard,Doxygen的GUI版本。

1.2HTML Help Workshop下载

如果你希望你的Doxygen自动生成chm,那么请下载HTML Help Workshop,我们将要使用当中的hcc.exe文件以及相关dll

http://www.microsoft.com/en-us/download/details.aspx?id=21138 进行下载

下载其中的htmlhelp.exe并安装,记住安装目录,我们将在Doxygen配置时使用。

1.3 Graphviz

graphviz 是一个由AT&T实验室启动的开源工具包,用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图,如不需要此功能可不安装该工具包。

安装并记录安装目录,同样我们一会需要配置Doxygen

 具体的作用是下面的:包括怎么生产Doxygen

首先在网上下载Doxygen,HTML Help Workshop。这两个软件直接在各自的官网上下载就行了。

然后使用doxywizard.exe生成一个Doxygen文件。点击“D:\program files\Doxygen\doxygen\bin\doxywizard.exe”出现如下界面:在Wizard属性页主要需要改一个地方,点击左侧的“Output”将右侧复选框中的LaTex中的钩去掉;然后在Step1:下面指定Doxygen的工作目录,就是这个向导生成的文件的存放路径。

在"Wizard"和“Export”中还有许多可以编辑的参数,暂时不修改,以后熟悉了再改。然后点击“Run”下面的“Run doxygen”就可以生成了脚本。

再点击“File”菜单中的"Save as",就可以生成我们需要的脚本了,将生成的脚本命名为default.doxygen如图:

default.doxygen就是普通的文本文件,在这里需要对它进行一些编辑,这些需要编辑的地方主要是字符编码的问题,其实在前面的图形化界面中也可以进行更改的。

主要需要修改的地方有如下几处:

GENERATE_HTMLHELP      = YES

OUTPUT_LANGUAGE        = Chinese

CHM_INDEX_ENCODING = gb2312

DOXYFILE_ENCODING=gb2312

INPUT_ENCODING=gb2312

然后这个default.doxygen就处理好了。

接下来是在vs中集成这些工具方便以后使用了。将default.doxygen拷贝到需要生成文档的工程下面

1.集成Doxygen

在VS环境中:Tools->External Tools->Add

Title: Doxygen

Command: D:\Program Files\doxygen\bin\doxygen.exe(doxygen的安装目录)

Arguments: $(ProjectDir)\default.doxygen

Initial directory: $(ProjectDir)

(可以把use output window复选框勾上)

点击Tools->Doxygen,将会在工程目录下生成html文件夹,里面的html文件就是自动生成的注释文件。

2.集成CHM制作工具HTML Help Workshop

首先安装HTML Help Workshop。

在VS环境中:Tools->External Tools->Add

Title: HTML Help Workshop

Command: D:\program files\Doxygen\htmlhelp\hhw.exe(HHW的安装目录)

Arguments: $(ProjectDir)html\index.hhp

Initial directory: $(ProjectDir)

点击Tools->HTML Help Workshop,就会出现HHW的窗体,编译,可得到index.chm文件。

注意:编译时,会弹出一个窗口确认路径名,而VS自动传入的路径名是有错误的,多了2个双引号,去掉双引号,编译,就可以成功了。如下图:

3.集成CHM文件查看工具hh.exe

在VS环境中:Tools->External Tools->Add

Title: ViewCHM

Command: C:\WINDOWS\hh.exe(windows自带)

Arguments: $(ProjectDir)html\index.chm

Initial directory:

点击Tools-> ViewCHM,就会看到index.chm文件了。

如果只要Html的注释,应该不用安装后面的两个了!

2.配置Doxygen

2.1基本配置

在基本配置中,会介绍一些关于Doxygen的基本配置,例如各种乱码,输出内容等。

首先我们打开开始-》所有程序-》Doxygen-》doxywizard

第一步,选择你的工作目录(配置文件位置  D:\Doxygen),点击Select。

第二步,进行配置

Wizard选项卡:

首先修改Project name,选择扫描源代码的目录,Source code directory:,勾选Scan recursively  (递归扫描),之后选择输出目录,作为测试选择桌面进行查看。

在Wizard的Topics下的Mode,选择All Entities,可以输出相对完整的功能,是否包含源代码看你自身情况,在下面选择好你的语言。这里作者使用的是C#  所以选择Java or C#

在Output中,如果你需要输出chm格式,请勾选。

在Diagrams中选择使用GraphViz包,来输出UML

Expert选项卡:

说明:编码格式,UTF-8 是首选。如果需要显示中文则选择GB2312.

TAB_SIZE 主要是帮助文件中代码的缩进尺寸,譬如@code和@endcode段中代码的排版,建议设置成4。

Build页面,这个页面是生成帮助信息中比较关键的配置页面:

EXTRACT_ALL 表示:输出所有的函数,但是private和static函数不属于其管制。

EXTRACT_PRIVATE 表示:输出private函数。

EXTRACT_STATIC 表示:输出static函数。同时还有几个EXTRACT,相应查看文档即可。

SHOW_INCLUDE_FILES 表示:是否显示包含文件,如果开启,帮助中会专门生成一个页面,里面包含所有包含文件的列

表。

INLINE_INFO :如果开启,那么在帮助文档中,inline函数前面会有一个inline修饰词来标明。

SORT_MEMBER_DOCS :如果开启,那么在帮助文档列表显示的时候,函数名称会排序,否则按照解释的顺序显

示。

说明:INPUT_ENCODING (输入的源文件的编码),要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。

总结:我查看到我的代码文件是utf-8的(vs2013中打开文件 选另存为可看到编码格式)((VS2012的话):文件->高级保存选项)。

在Expert的HTML中,首先要看HHC_LOCATION选项,添加安装目录(注:作者目录为C:/Program Files (x86)/HTML Help Workshop/hhc.exe)

勾选CHM_INDEX_ENCODING,在你源代码中的字符集是什么就填写什么,

之后在Expert的Dot中勾选CLASS_DIAGRAMS,UML_LOOK

为了减少chm体积,在DOT_IMAGE_FORMAT中选择gif或者jpg,均可。

最后选择好DOT_PATH所输出的位置。

点击 Run doxygen 按钮, Doxygen 就会从源代码中抓取符合规范的注释生成你定制的格式的文档。

几个错误:

Error: When enabling GENERATE_HTMLHELP the search engine (SEARCHENGINE) should be disabled. I‘ll do it for you.

warning: The selected output language "chinese" has not been updated

since release 1.8.2. As a result some sentences may appear in English.

解决:把HTML里面的SEARCHENGINE设置为NO

接下来的工作就是学习 doxygen 的注释规范了,参考 《doxygen 快速入门》第 2 节 “常用注释语法”。慢慢的就可以体会到 doxygen 的方便性。

3、doxygen 的注释规范

并非所有程序代码中的批注都会被Doxygen 所处理。您必需依照正确的格式撰写。原则上,Doxygen 仅处理与程序结构相关的批注,如
Function,Class ,档案的批注等。对于Function内部的批注则不做处理。Doxygen可处理下面几种类型的批注。

JavaDoc类型:

/**
 * ... 批注 ...
 */

Qt类型:

/*!
 * ... 批注 ...
 */

单行型式的批注:

/// ... 批注 ...

//! ... 批注 ...

要使用哪种型态完全看自己的喜好。以笔者自己来说,大范围的注解我会使用JavaDoc 型的。单行的批注则使用"///" 的类型。

此外,由于Doxygen 对于批注是视为在解释后面的程序代码。也就是说,任何一个批注都是在说明其后的程序代码。如果要批注前面的程
式码则需用下面格式的批注符号。

/*!< ... 批注 ... */
/**< ... 批注 ... */
//!< ... 批注 ...
///< ... 批注 ...

上面这个方式并不适用于任何地方,只能用在class 的member或是function的参数上。

举例来说,若我们有下面这样的class。
    class MyClass {
        public:
            int member1 ;
            int member2:
            void member_function();
    };
    
加上批注后,就变成这样:

/**
     * 我的自订类别说明 ...
     */
    class MyClass {
        public:
            int member1 ; ///< 第一个member说明 ...
            int member2:  ///< 第二个member说明 ...
            int member_function(int a, int b);
    };
    
    /**
     * 自订类别的member_funtion说明 ...
     *
     * @param a 参数a的说明
     * @param b 参数b的说明
     *
     * @return 传回a+b。
     */ 
    int MyClass::member_function( int a, int b ) 
    {
        return a+b ;
    }
    
当您使用Doxygen 产生说明文档时,Doxygen 会帮您parsing 您的程式码。并且依据程序结构建立对应的文件。然后再将您的批注,依据其位置套入于正确的地方。您可能已经注意到,除了一般文字说明外,还有一些其它特别的指令,像是@param及@return 等。这正是Doxygen 另外一个重要的部分,因为一个类别或是函式其实都有固定几个要说明的部分。为了让Doxygen 能够判断,所有我们就必需使用这些指令,来告诉Doxygen 后面的批注是在说明什么东西。Doxygen 在处理时,就会帮您把这些部分做特别的处理或是排版。甚至是制作参考连结。
首先,我们先说明在Doxygen 中对于类别或是函数批注的一个特定格式。
    /**
     * class或function的简易说明...
     *
     * class或function的详细说明...
     * ...
     */ 
上面这个例子要说的是,在Doxygen 处理一个class 或是function注解时,会先判断第一行为简易说明。这个简易说明将一直到空一行的出现。或是遇到第一个"." 为止。之后的批注将会被视为详细说明。两者的差异在于Doxygen 在某些地方只会显示简易说明,而不显示详细说明。如:class 或function的列表。

另一种比较清楚的方式是指定@brief的指令。这将会明确的告诉Doxygen,何者是简易说明。例如:
    /**
     * @brief class或function的简易说明...
     *
     * class或function的详细说明...
     * ...
     */

除了这个class 及function外,Doxygen 也可针对档案做说明,条件是该批注需置于档案的前面。主要也是利用一些指令,通常这部分注解都会放在档案的开始地方。如:

/*! \file myfile.h
        \brief 档案简易说明
    
        详细说明.
        
        \author 作者信息
    */

如您所见,档案批注约略格式如上,请别被"\" 所搞混。其实,"\" 与"@" 都是一样的,都是告诉Doxygen 后面是一个指令。两种在Doxygen 都可使用。笔者自己比较偏好使用"@"。
接着我们来针对一些常用的指令做说明:


@file


档案的批注说明。


@author


作者的信息


@brief


用于class 或function的批注中,后面为class 或function的简易说明。


@param


格式为

@param arg_name 参数说明

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


@return


后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。


@retval


格式为

@retval value 传回值说明

主要用于函式说明中,说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。

Doxygen 所支持的指令很多,有些甚至是关于输出排版的控制。您可从Doxygen的使用说明中找到详尽的说明。

下面我们准备一组example.h 及example.cpp 来说明Doxygen 批注的使用方式:

example.h:

/**
     * @file 本范例的include档案。
     *
     * 这个档案只定义example这个class。
     *
     * @author [email protected]
     */
            
    #define EXAMPLE_OK  0   ///< 定义EXAMPLE_OK的宏为0。
    
    /**
     * @brief Example class的简易说明
     *
     * 本范例说明Example class。
     * 这是一个极为简单的范例。
     * 
     */
    class Example {
        private:
            int var1 ; ///< 这是一个private的变数
        public:
            int var2 ; ///< 这是一个public的变数成员。
            int var3 ; ///< 这是另一个public的变数成员。
            void ExFunc1(void); 
            int ExFunc2(int a, char b);
            char *ExFunc3(char *c) ;
    };
    
    
example.cpp:

/**
     * @file 本范例的程序代码档案。
     *
     * 这个档案用来定义example这个class的
     * member function。
     *
     * @author [email protected]
     */
    
    /**
     * @brief ExFunc1的简易说明
     *
     * ExFunc1没有任何参数及传回值。
     */
    void Example::ExFunc1(void)
    {
        // empty funcion.
    }

/**
     * @brief ExFunc2的简易说明
     *
     * ExFunc3()传回两个参数相加的值。
     *
     * @param a 用来相加的参数。
     * @param b 用来相加的参数。
     * @return 传回两个参数相加的结果。
     */
    int ExFunc2(int a, char b)
    {
        return (a+b);
    }
    
    /**
     * @brief ExFunc3的简易说明
     *
     * ExFunc3()只传回参数输入的指标。
     *
     * @param c 传进的字符指针。
     * @retval NULL 空字符串。
     * @retval !NULL 非空字符串。
     */
    char * ExFunc2(char * c)
    {
        return c;
    }

时间: 2024-10-14 13:52:11

在VS2103环境中集成Doxygen工具的相关文章

windows环境中利用NMake工具编译连接C++源代码

这篇文章是上一篇文章(http://www.cnblogs.com/LCCRNblog/p/4532643.html)的补充,因此需要先看看上一篇文章. 最近在写代码的时候,需要通过命令的方式来执行生成的c++源代码文件,因此需要学习有关windows环境下如何使用命令来编译连接c++原文件.这一篇文章是自己慢慢摸索实践得出的.作为自己入门的起点吧,后续还要好好深入理解这方面的知识. 1.准备 编写好main.cpp header.h header.cpp这三个源代码文件,并放入一个文件夹tes

ueditor1.4.3在.net环境下的vs开发工具中集成经验

Ueditor是个很不错的在线富文本编辑器,几个项目一直使用它.最近想更新版本,发现新版1.4.3与旧版的部署方式完全不一样了,官网文档介绍的是直接放在iis下的部署说明,没有提到在vs开发工具中如何集成,自己新建了一个测试项目琢磨了一会,测试没啥问题,记录下给大家分享. 项目结构如下图: 因为我创建的是web项目类型,所以把controller.ashx以项目形式的一般处理程序迁移过去,并重命名成ueditor.ashx(记得在ueditor.config.js修改服务器统一请求接口路径).另

让你提前认识软件开发(51):VC++集成开发环境中Linux下Pclint工程的配置方法及常见错误修改

第3部分 软件研发工作总结 VC++集成开发环境中Linux下Pclint工程的配置方法及常见错误修改 [文章摘要] Pclint是一种C/C++软件代码静态分析工具.它是一种更加严格的编译器,能够发现普通编译器所不能发现的代码中的很多问题,因此被广泛应用于软件开发项目中. 本文介绍了如何在VC++集成开发环境中配置Linux下的Pclint工程,给出了C语言中pclint规则A检查的常见错误,并描述了对应的修改办法. [关键词] VC++  Pclint  配置  操作  修改 1. 前言 P

Android开发环境中的概念和工具介绍

最近学习Android开发,以前使用C/C++多一些,现在再补点Java知识,不管是哪种语言,都不过是一种工具而已,真的学起来,大同小异,无谓优劣.学习Android编程肯定是要先从环境搭建开始,无论是在Windows.还是Linux.Mac环境都可以,在搭建环境之前,有些概念综合了解一下确有必要,本文即是面向Android初学者的文章,作为Android入门的启蒙篇章. Android是Google主导开发的基于Linux开源智能移动终端操作系统,当然这里说的开源,也不是说Google把所有的

.NET程序员项目开发必知必会—Dev环境中的集成测试用例执行时上下文环境检查(实战)

Microsoft.NET 解决方案,项目开发必知必会. 从这篇文章开始我将分享一系列我认为在实际工作中很有必要的一些.NET项目开发的核心技术点,所以我称为必知必会.尽管这一些列是使用.NET/C#来展现,但是同样适用于其他类似的OO技术平台,这些技术点可能称不上完整的技术,但是它是经验的总结,是掉过多少坑之后的觉醒,所以有必要花几分钟时间记住它,在真实的项目开发中你就知道是多么的有帮助.好了,废话不说了,进入主题. 我们在开发服务时为了调试方便会在本地进行一个基本的模块测试,你也可以认为是集

将CKEditor集成到Java开发环境中

本文主要介绍如何将CKEditor集成到Java开发环境中,CKEditor是FCKEditor的升级版,使用很方便.下面是基本使用方法: 第一步:下载必要的库 1.到CKEditor官网http://www.fckeditor.net/download/下载Ckeditor4.0.2,这是目前最新的版本,4.1马上就出来了. 2.找到CKEditor 3.6.4 for Java,download.jar按钮,下载ckeditor-java-core-3.5.3.zip,这是java集成的ja

利用开发框架中的标签库集成报表工具

在项目开发中,完成数据录入后,统计分析报表是必定要出的,后期还会应客户要求出现更多的统计分析报表. 集成一个成熟的报表工具来应对各种复杂和多变的报表是最好不过的了. java的开发框架很多都利用标签库来实现表现层与业务层的分离和结合,也使java的项目开发更加简洁和易于维护.集成了struts标签库的jsp页面,标签库本身有一些判断循环的逻辑,又能方便的获取后端的数据,被大部分的java开发框架利用,jsp页面本身也不用太多的js和java的代码混合.使得表现层的代码一目了然,方便后期的维护.

基于Metronic的Bootstrap开发框架经验总结(18)-- 在代码生成工具Database2Sharp中集成对Bootstrap-table插件的分页及排序支持

在我们开发系统界面,包括Web和Winform的都一样,主要的界面就是列表展示主界面,编辑查看界面,以及一些辅助性的如导入界面,选择界面等,其中列表展示主界面是综合性的数据展示界面,一般往往需要对记录进行合理的分页,集成各种增删改查的按钮等功能.随着开发项目的需求辩护,对数据记录分页展示.排序等功能都是常态的要求,因此在代码生成工具中调整了主列表界面的列表展示插件为Bootstrap-table插件,本篇随笔主要介绍在代码生成工具Database2Sharp中集成对Bootstrap-table

eclipse中集成python开发环境

Eclipse简介 Eclipse是java开发最常用的IDE,功能强大,可以在MAC和Windos上运行,学习简单. pydev简介 一个功能强大的 Eclipse插件,用户可以完全利用 Eclipse 来进行 Python 应用程序的开发和调试.它提供了一些很好的功能,如:语法错误提示.源代码编辑助手.Quick Outline.Globals Browser.Hierarchy View.运行和调试等等.拥有诸多强大的功能,同时也非常易于使用. 详细步骤 1.安装python环境 下载地址