使用Doxygen构建文档系统

Posted 2023-04-24

参考技术A

　　如果您这次还没来得及使用老式的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 VarInA; int 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

如何使用 Doxygen 和 Doxygen::Filter::Perl 为 Perl 子例程生成文档？

【中文标题】如何使用 Doxygen 和 Doxygen::Filter::Perl 为 Perl 子例程生成文档？

【英文标题】：How to use Doxygen and Doxygen::Filter::Perl to generate documentation for Perl sub routines?

【发布时间】：2015-05-16 00:37:05

【问题描述】：

我正在尝试弄清楚如何使用Doxygen::Filter::Perl 为 Perl 文件生成文档。我从一个非常简单的文件开始，只是为了看看我是否可以让它工作（test_doxygen.pl）：

#! /usr/bin/env perl
#** @file test_doxygen.pl
#  @brief  Testing Doxygen using Doxygen::Filter::Perl
#
# Description of the purpose of this file
#
#  @author Håkon Hægland ([e-mail])
#
#  @bug No known bugs.
#
#*

#** @class main
# The main class
#*

use strict;
use warnings;

my $b = add_one(1);

#** @function public add_one ($par1)
# @brief A brief description of the function
#
# A detailed description of the function
# @params $par1   required  A number
# @retval value   Input value plus one1
#*
sub add_one 
    my ($par1) = @_;

    return $par1 + 1;

然后我安装了 Doxygen::Filter::Perl 并使用了 metacpan.org (the link is here) 的包维护者提供的 Doxyfile 配置文件 并将其放在与上面脚本相同的目录中。我在Doxyfile中更改了一行：INPUT标签的值从lib改为空字符串，以便只搜索当前目录的源文件..

我使用的是Ubuntu 14.04，所以我用sudo apt-get install doxygen安装了Doxygen，（我还需要安装graphviz:sudo apt-get install graphviz）然后我终于运行了

$ doxygen

从终端窗口。生成的 HTML 文件 doc/html/index.html 包含有关文件和作者的文档，但它不包含 add_one 子例程的任何文档。

我在这里错过了什么？

更新

以下是 Chromium 浏览器中类视图的外观：

正如所见，add_one 子例程没有引用/链接。

这是文件视图：

【问题讨论】：

您错过了 Perl 程序员使用 pod 的想法？

@mob 读完这个***.com/questions/4722619/… 我决定试试 Doxygen :)

【参考方案1】：

所以问题在于处理“我的”变量声明。它将值设置为私有：并且 doxygen 从未返回。我在 Perl.pm 中添加了一行来解决这个问题，它现在应该对你有用。由于您使用的是 pl 文件而不是 pm 文件，因此我还对 Doxyfile 进行了更改，因此您将希望从发行版中获取新文件。我已将 1.71 发布到 Github 和 CPAN，并使用您的确切示例对其进行了测试。

【讨论】：

谢谢乔丹。它现在正在工作！看起来不错，感谢您抽出宝贵时间。

【参考方案2】：

我刚刚将 Doxygen::Filter::Perl 的新版本发布到 Github 和 CPAN，版本 1.70。这应该可以解决您看到的问题。

【讨论】：

谢谢@jordan2175。但它仍然不起作用。我运行cpanm Doxygen::Filter::Perl 更新到1.70 版。然后重新运行doxygen 命令，但我仍然得到相同的结果。在浏览器的类视图或文件视图中没有add_one 子例程..

【参考方案3】：

我刚刚看了这个，它似乎可以与 Doxygen (1.7.5.1) 一起使用，但是，较新版本的 Doxygen (1.8.9.1) 似乎不能很好地工作。

【讨论】：

谢谢@jordan2175。我使用的是 1.8.6 版。