使用Doxygen构建文档系统

2023-02-20 12:03:02html-css05

使用Doxygen构建文档系统,第1张

如果您这次还没来得及使用老式的Help Workshop为您的Web应用构建文档系统的话那么何不尝试一下Doxygen 需知 The proof of the pudding lies in the eating

Doxygen是什么？

Doxygen是一种开源跨平台的以类似JavaDoc风格描述的文档系统完全支持C C++ Java Objective C和IDL语言部分支持PHP C# 注释的语法与Qt Doc KDoc和JavaDoc兼容 Doxgen可以从一套归档源文件开始生成HTML格式的在线类浏览器或离线的LATEX RTF参考手册对于未归档的源文件也可以通过配置Doxygen来提取代码结构或者借助自动生成的包含依赖图（include dependency graphs）继承图（inheritance diagram）以及协作图（collaboration diagram）来可视化文档之间的关系 Doxygen生成的帮助文档的格式可以是CHM RTF PostScript PDF HTML和Unix man page等

Doxygen在Linux上开发但也可以在其它的Unix平台下运行而且 Windows x/NT平台下也有对应的可执行版本

安装Doxygen

首先去Doxygen网站上找到最新版本的Doxygen 有二进制或源码两种版本如果不想重头编译下载二进制版本安装即可在Linux下源码编译需要perl和Gnu工具flex bison make的支持在Windows下二进制版本勿需安装而源码编译所需支持工具较多我们仅讲述Linux下的Doxygen的源码编译以及二进制版本安装过程

编译源码

gunzip doxygen $VERSION src tar gz tar xf doxygen $VERSION src tar sh /configure 或者configure platform platform type （略去直接使用configure需要平台检测的过程平台类型在PLATFORMS文件中列出） configure with doxywizard（GUI前端选项） make 或者make docs（创建HTML格式的手册） make pdf（创建PDF格式的手册）

安装二进制版本

/configure make install

二进制文件安装目录是<prefix>/bin 其中<prefix>缺省为/usr 可以通过configure的参数 prefix修改其值使用make install_docs可以把文档和例子安装在目录<docdir>/doxygen 其中<docdir>缺省为<prefix>/share/doc/packages 可以通过configure的参数 docdir修改其值 doxygen是bin目录下的一个命令行程序它是Doxygen的核心工具完成文档的转换和生成工作

Doxygen的处理流程

图是Doxygen网站上给出的Doxygen处理工具以及它们之间的信息流

从图中可以看出 Doxygen可执行程序位于正中所有的流程都围绕着它进行左侧图标表示Doxygen的输入可以是源文件或者是定制的头文件图像注解等 Doxygen图标上部是配置文件由Doxywizard处理下部是Tag文件由Doxytag处理后面是Doxygen输出文件的类型依次是XML Latex Man pages RTF和HTML 可处理类型图标之后是进行进一步转换所需的工具

图 Doxygen网站上给出的Doxygen信息流图

配置文件

每一个Doxygen工程都有一个后缀为 cfg的配置文件用来保存所有的设置配置文件的格式与autoexec bat config sys等文件相似是由名称/值对组成的ASCII码会由doxygen命令来解析为了简化创建和修改配置文件 Doxygen可以在命令行方式下加上参数 g自动创建模板文件

doxygen g <config file>

忽略<config file>将会生成一个名为Doxyfile的缺省文件如果<config file>已经存在会被Doxygen改名为<config file>bak

实际上我们根本就不需要用一般的编辑器来编辑配置文件 Doxygen提供了一个辅助工具Doxywizard Doxywizard是Doxygen的GUI前台用户可以能过它来读写配置文件省却了手工配置的麻烦基本上在Doxywizard中可以完成Doxygen的绝大多数工作而且Doxygen也可以在由Doxywizard启动这样就使得整个过程比较连贯

虽然如此我们还是要理解常见的各个Tag的含义在Doxywizard中可以看到这些Tag以自明的方式命名我们大致可以从名称中看出其作用这些Tag被Doxywizard大致分为几类其中HTML到PerlMod是输出文件种类设置 Project是Doxygen工程设置 Build是编译类选项 Messages为出错或异常选项 Input为输入源选项等等

图 Doxywizard

注释

Doxygen规定了进行注释的一些格式正确的注释才能使Doxygen生成文档第一个代码条目都有两种描述简要描述和详细描述两者都是可选的简要描述只有一行而详细描述则提供更长更仔细的描述 Doxygen只允许有一个简要描述和详细描述

在Doxygen中一般只会处理与程序结构相关的注释函数内部的注释通常不做处理对于详细描述来说有下面几种表示方式

JavaDoc风格中间的 * 号可选 /** * 注释 */ Qt风格中间的 * 号可选 /*! * 注释 */ C++风格的变体或者最后一个 / 改为！也可以 /// 单行注释 /// 注释 /// 更加显著的表示 /////////////////////////////////////////// /// 注释 /////////////////////////////////////////// 简要描述亦有多种表示方式在上述注释块中使用\brief命令详细注释在空行之后开始 /*! \brief 简要描述 * 继续 * * 详细注释 */ JAVADOC_AUTOBRIEF设置为YES后在JavaDoc风格的注释中第一个点号之前的内容被自动设置为简要描述对于多行C++变体这个选项亦会起到相同的作用 /** 简要描述详细描述 * 注释 */ C++变体风格 /// 简要描述 /* 详细描述 */

命令

Doxygen支持的指令非常多主要作用是控制输出文档的排版格式命令以 \ 或 @ 号开始

一些命令可以有多个参数一些命令只有一个参数参数周围的括号使用是有含义的

<>号表示参数是单个词 ()号表示参数一直会到行尾 {}号表示参数会扩展到下一段落 []号表示参数是可选的

下面章节中也涉及到一些命令的使用其它的命令可以查阅Doxygen用户手册

列表

Doxygen有许多方法可以创建项目列表

使用在每行开始之前打头使用可以结束一个列表开始新的段落使用这种方法要严格对齐 /** * 表项一 * 子项一 * 子项二 * * */ 在文档块中使用HTML命令这种方法不需要严格对齐 /*! * <ul>* <li>表项一 * <ol>* <li>子项一 * <li>子项二 * </ol>* <li>表项二 * </ul>*/

分组

Doxygen有两种分组机制第一种是全局地为每一个组创建一个网页此时分组被称为 module 第二种是用于复合实体中的成员列表此时分组被称为 member group Module是一种把内容在单个网页上分组的方法分组可以包括files namespace classes functions variables enums typedefs和defines 也可以包含其它分组复合实体（pound entities）如类文件命名空间等可以分布在多个分组中而成员实体（member）如变量函数 typedef等只能归属于一个分组

定义分组的方法是在特殊注释块中使用命令\defgroup和\addtogroup defgroup的格式如下

\defgroup <唯一标识名>（中间可以有空格的标题）

两次使用同一标识名在doxygen解析的时候会出现错误命令addtogroup与defgroup不同的地方在于如果使用了同一标识则会在改组中加入新的项如果标识不重复则会创建分组 addtogroup中的标题是可选的

声明分组之后如果要使某个实体归属某一分组需要使用ingroup命令避免在每个成员之前都使用ingroup命令可以将member用@{和@}封装起来

/** * \ingroup A */ extern int VarInA/** * \defgroup IntVariables Global integer variables */ /*@{*/ /** an integer variable */ extern int IntegerVariable/*@}*/ /** * \defgroup Variables Global variables */ /*@{*/ /** a variable in group A */ int VarInAint IntegerVariable/*@}*/

上面这些命令都是有优先级的 doxygen会根据优先级将实体放入具有最高优先级的分组之中它们的优先级顺序是 ingroup defgroup addtogroup weakgroup weakgroup类似一个低优先级的addtogroup 在 h文件中可以使用高优先级的命令定义层次结构在 c文件中\weakgroup就不需要准确遵循 h文件中定义的层次结构

如果要把不同的类型归入同一分组内就要使用Member group 它的定义方法如下

//@{ //@} 或者 /*@{*/ /*@}*/

Member group不可以嵌套

图表

Doxygen里有内置生成C++类层次图的功能它使用贝尔实验室开发的graphviz 中的工具 dot 来生成更高级的图表使用这个工具时要将配置选项HAVE_DOT设为YES

当GRAPHICAL_HIERARCHY设置为YES时将会绘制一个图形表示的类图结构当CLASS_GRAPH设置为YES时会为每个归档的类创建一张图表示其直接或间接的继承关系当INCLUDE_GRAPH设置为YES时会为每个归档文件创建一幅包含依赖图此功能目前仅有HTML和RTF格式支持当COLLABORATION_GRAPH设置为YES时会为每个归档类或结构绘制基类继承关系图和使用关系图当CALL_GRAPH设置为YES时会为每个函数显示一幅直接或间接调用关系图

更具体的信息可以参考Doxygen的手册

公式

Doxygen可以把LaTeX格式的公式输出出来要在HTML文档里包含公式需要安装下面的工具 latex（LaTeX编译器） dvips（将DVI文件转换为PS文件） gs（将PS文件转换为位图）

包含公式的方法有两种

使用\f$命令对表示文本中间的公式遵循LaTeX格式 \f$(x_ y_ )\f$ (x y ) 位于独立一行上未编号的公式应放在命令\f[和\f]之间 \f[ |I_ |=\left| \psi(t) \right| \f] 对应的输出是|I |=|ψ(t)|

中文文档

Doxygen支持多种语言输出中文文档的时候只需要将配置文件中的OUTPUT_LANGUAGE标签设置为Chinese即可（用Doxywizard修改更方便）

有一个需要注意的问题是在Windows下的浏览器浏览中文HTML文档时英文字母会变得很难看解决的办法是将doxygen_cn css下载到本地硬盘并将配置文件中的HTML_STYLESHEET修改为这个文件的位置

HTML_STYLESHEET=c:\doxygen\doxygen css

运行doxygen

在命令行下运行doxygen是很简单的只需要指定配置文件即可

doxygen project cfg

或者也可以使用Doxywizard在配置完后直接运行doxygen

lishixinzhi/Article/program/Java/hx/201311/26448

常见的云服务器管理工具：

1、远程桌面连接

Remote Desktop - 远程桌面连接主要是用于对远程托管的服务器进行远程管理，使用非常方便，如同操作本地电脑一样方便。远程服务器端必须要先安装“远程桌面连接”的服务器端程序，然后客户端可以通过远程桌面来管理服务器了。

2、FTP服务软件和客户端

服务器FileZilla-将客户端的文件上传到服务器上，这个最常用的软件是FTP了，微软的IIS自带了一个简单的FTP服务器管理软件，如果觉得不好用，服务器上也可以安装免费的FileZilla服务器管理软件，客户端可以使用免费的FileZilla Client，支持多线程上传文件。

3、Arp防火墙

Arp Firewall - 现在托管服务器必须安装的个软件是Arp防火墙，没办法啊，中国这网络环境，不安装Arp防火墙等着被人挂木马了。现在免费的Arp防火墙主要有两款，一个是奇虎的360 Arp防火墙，一个是金山Arp防火墙。

4、硬件检测

CPU-Z - CPU-Z是一款免费的系统检测工具，可以检测CPU、主板、内存、系统等各种硬件设备的信息。它支持的CPU种类相当全面，软件的启动速度及检测速度都很快。另外，它还能检测主板和内存的相关信息，其中有我们常用的内存双通道检测功能。远程管理服务器的时候，使用这个软件可以对服务器的硬件信息一清二楚。

5、流量监控

DU Meter - DU Meter是一个简单易用的网络流量监视工具，图形化的界面显示非常直观，可以实时监测服务器的上传和下载的网速，同时还有流量统计功能。可以分析出日流量、周流量、月流量等累计统计数据。不过遗憾的是这个软件不是免费的。

6、进程监控

Process Explorer - Process Explorer是一款免费的进程监视工具，功能比Windows自带的任务管理器要强大的多，不仅可以监视、暂停、终止进程，还可以查看进程调用的DLL文件，是预防病毒、查杀木马的好帮手。

7、日志分析

WebLog Expert - 虽然Google Analytics是一款强大的免费的网站分析服务，但必须加入统计代码才能使用，WebLog Expert则可以直接分析网站的访问日志文件，通过日志文件分析出网站的站点访问者、活动统计、文件访问量、搜索引擎、浏览器、操作系统和错误页面等等众多的统计信息，是网络监测的好助手。这个软件本身不免费，不过其另一个版本WebLog Expert Lite是免费的。

8、日志搜索

WinHex - WinHex是一款速度很快的文件编辑器。打开数百兆的大型文件速度飞快，使用WinHex可以轻松打开服务器上的大型日志文件，并对其进行关键字搜索，效果非常好，是我见到的速度的文本编辑搜索软件，总体来说是一款非常不错的16进制编辑器。

9、代码编辑

Notepad++ - Notepad++是一个免费开源的源程序代码、HTML网页代码编辑工具，支持多达数十种常见源代码或脚本的语法，包括C，C++，Java，C#，XML，HTML，PHP，Javascript，RC resource file，makefile，ASCII，doxygen，ini file，batch file，ASP ，VB/VBS，SQL，Objective-C，CSS，Pascal，Perl，Python，Lua等，功能非常强大。在服务器上安装后可以直接修改网站上的源程序代码。

十大常见的服务器管理软件

当网站发展到一定的规模，站长应该开始考虑要为网站托管服务器。通常情况下服务器会被放到BGP机房，网站管理员通过远程来管理服务器。在网站服务器进行托管时，需要在服务器上安装一些服务器管理软件，才能更为有效地管理这台远程服务器，我根据我自己的管理经验，推荐十个有用的服务器管理软件，供大家参考和分享。

1、远程桌面连接

远程桌面连接（以前称为“终端服务客户端”）主要是用于对远程托管的服务器进行远程管理，使用非常方便，如同操作本地电脑一样方便，而远程桌面连接工具，我个人喜好IIS7。

IIS7远程桌面管理工具(3389、vps、服务器批量管理、批量远程工具) 是一款绿色小巧，功能实用的远程桌面管理工具，其界面简洁，操作便捷，能够同时远程操作多台服务器，并且多台服务器间可以自由切换，适用于网站管理人员使用。软件下载地址：iis7远程桌面管理工具下载

2、Arp防火墙

3、FTP服务和客户端

FileZilla - 将客户端的文件上传到服务器上，最常用的软件是FTP了，微软的IIS自带了一个简单的FTP服务器管理软件，如果觉得不好用，服务器上也可以安装免费的FileZilla服务器管理软件，客户端可以使用免费的FileZilla Client，支持多线程上传文件。

4、硬件检测

5、流量监控

6、端口监控

TcpView - TcpViews是一款免费的端口和线程监控工具，可以列出当前所有TCP和UDP端口的进程清单，包括本地和远程地址的TCP连接，其实和系统命令netstat类似，不过是GUI界面的，使用方便，占用资源少，默认字体在中文环境下很小，需要手动修改。在服务器上运行的话，默认刷新时间不要用默认的1秒。

7、进程监控

8、日志分析

9、日志搜索

10、代码编辑

词库加载错误未能找到文件“E高铁采集器内存溢出ConfigurationDictStopwordstxt”

# 上一篇：下载什么就能拍出装

# 下一篇：如何判断台式电脑主机硬件的好坏？