Doxygen源码分析: 子目录简要介绍

2023-05-18 23:56:46
ChrisZZ imzhuo@foxmailcom
Hompage https://github.com/zchrissirhcz

1. doxygen 版本

zz@Legion-R7000P% git log             
commit acb04c2a27e29b82e697d20ac0561034f0a16e20 (HEAD -> master, origin/master, origin/HEAD)
Author: Dimitri van Heesch <doxygen@gmail.com>
Date:   Sun May 14 12:12:28 2023 +0200

    Rename GENERATE_SITEMAP to SITEMAP_URL

2. doxygen 目录结构

列出第一层目录

$ find . -maxdepth 1 -type d | sort -V
.
./.git
./.github
./addon
./cmake
./deps
./doc
./doc_internal
./examples
./libversion
./libxml
./src
./templates
./testing
./vhdlparser
./winbuild

$ find . -maxdepth 1 -type d | sort -V | wc -l
16

.git 目录

存储了 doxygen 历史提交记录。虽然是从 2013 年从 svn 切换到 git 的， 但是 git 可以导入 svn 提交记录， 而 doxygen 最早提交记录在 1999 年：

* 38d26d907e 2000-01-13 | add TopLevelAdmin=yes to keep all checkouts `rooted' [Dimitri van Heesch]        
* 3a0442f6ec 1999-12-15 | add doxygen alias [Dimitri van Heesch]
* df5aeefd51 1999-12-15 | mods for doxygen-0.49-991205 [Dimitri van Heesch]
* dc2968f7b4 1999-12-15 | mods for doxygen-0.49-991117 [Dimitri van Heesch]
* 916d6d5c6f 1999-12-15 | mods for doxygen-0.49-991106 [Dimitri van Heesch]
* a54eecdf4b 1999-12-15 | mods for doxygen-0.49-991003 [Dimitri van Heesch]
* 1d4e23de96 1999-12-15 | mods for doxygen-0.49-990901 [Dimitri van Heesch]
* ee8333a5d2 1999-12-15 | mods for doxygen-0.49-990829 [Dimitri van Heesch]
* 6aa7383e23 1999-12-15 | mods for doxygen-0.49-990728 [Dimitri van Heesch]
* e04496cb64 1999-12-15 | mods for doxygen-0.49-990522 [Dimitri van Heesch]
* 322885a870 1999-12-15 | initial version [Dimitri van Heesch]
* 361bf7915b 1999-12-15 | add gif handling [Dimitri van Heesch]
* 388dcb2a15 1999-12-13 | initial checkin [Dimitri van Heesch]
* b40b59f734 1999-12-13 | initial checkin [Dimitri van Heesch]
* a6238a4898 1999-12-13 | New repository initialized by cvs2svn. [Dimitri van Heesch]

.github 目录

用于 github action 方式的 CI/CD 脚本。

workflows/build_cmake.yml

基于 cmake 方式构建。支持的操作系统、编译器、构建类型（debug还是release）比较全面:

{ubuntu, macOS, windows} x {gcc, clang} x {Debug, Release}

workflows/coverity.yml

执行编译， 然后生成测试覆盖率报告。

workflows/docer_publish.yml

发布 docker 包。

addon 目录

插件目录， 包括了6个插件， 每个插件对应一个子目录

• doxmlparser
• doxyapp
• doxyparse
• doxypysql
• doxysearch
• doxywizard

doxmlparser 目录

是一个python包，可以更容易地解析doxygen生成的XML输出。
API是使用Dave Kuhlman的generateDS从index.xsd和compound.xsd XML模式文件生成的https://www.davekuhlman.org/generateDS.html。
请参阅examples目录，了解如何使用python模块

doxyapp 目录

是一个例子程序， 展示了如何把 doxygen 作为“源解析引擎”嵌入到应用程序中， 展示了如何在不生成 xml、html等输出的情况下运行 doxygen， 以及如何用使用从源代码中找到的符号信息。

这种方式 license 不友好， 要求获得 GPL 许可。

doxyparse 目录

这个目录包含一个基于 doxyapp 代码的 “源代码引擎”。 Doxyparse 修改 Doxygen 的默认输出， 并以 YAML 格式存储代码元素之间的依赖关系， 而不是生成用于人类阅读的格式。 换言之 Doxyparse 生成的东西是给机器看的。

Doxyparse 被看作是一个源代码静态分析工具， 被用在了很多的软件工程研究中： 软件测量， 质量测量等。Doxyparse 最开始被 Anlizo(https://www.analizo.org) 工具使用， 它是一个“源代码分析工具”套件， 目的是实现语言独立性和可扩展性、能够提取和计算相当数量的源代码度量结果， 生成依赖图， 以及其他的软件演进过程分析。

Doxyparse 有对应的论文： https://scholar.google.com.br/scholar?q=doxyparse

Doxyparse 原本是独立项目， 现在则在 doxygen 代码仓库中存放和开发。

doxypysql 目录

是一个 python 小工具， 用于在 doxygen_sqlite3.db 数据库文件中执行查询。

doxysearch 目录

没有说明文件。C++ 代码。 看起来是是建立 doxygen 索引、 执行 doxygen 搜索的插件， 主要疑问是为什么没放在 src 目录下。

doxywizard 目录

Doxywizard是一个图形前端，用于读取/编辑/写入doxygen配置文件和启动doxygen。它需要Qt 4.3或更高版本。

嗯，这是个给小白用户使用的界面工具， 简单易用。

cmake 目录

存放 CMake 构建过程中用到的辅助脚本。内容较多， 等后续分析构建过程时再仔细阅读分析。

deps 目录

dependencies 的缩写， 意思是依赖库。 这里的依赖并不仅是 C++ 依赖， 还包括 html 相关的 js 库等, 包括这几个目录:

• filesystem
• jquery
• liblodepng
• libmd5
• libmscgen
• spdlog
• svg
• TinyDeflate

filesystem 目录

使用了 ghc::filesystem 这个 header-only 的文件系统库:

A C++17-like filesystem implementation for C++11/C++14/C++17/C++20

实际上目前 doxygen 的 CMake 中已经使用 C++17 标准进行构建了， ghc::filesystem 估计可以删了。

jquery 目录

用于生成 doxygen 的 jquery.js 文件。

是 javascript 库 jquery 本体以及相关包的最小化版本合集，用于 html 页面显示：

• jquery 3.6.0: https://jquery.com/download/
• jquery.ui 1.13.2: https://github.com/jquery/jquery-ui
  modules required:
  • jquery.ui.core all
  • jquery.ui.interactions resizable
  • jquery.ui.widgets mouse
• jquery.scrollTo: 2.1.2: https://github.com/flesler/jquery.scrollTo
• jquery.powertip: 1.3.1: https://stevenbenner.github.io/jquery-powertip/
• jquery.touchpunch: 0.2.3: http://touchpunch.furf.com/ + fix for issue 303
• jquery.smartmenus: 1.1.0: https://www.smartmenus.org/

由于 jquery 自身有性能问题， 本目录存放的 jquery 是魔改的： 删掉了 destroy 方法。

liblodepng 目录

是一个轻量级三方库， C语言， 作者是 Lode Vandevenne， 是一个 png 的编解码库。版本是 LodePNG 20080927, 不带 SIMD 优化。

libmd5 目录

是一个轻量级三方库， C语言， 作者是 Colin Plumb, 1993年的作品。用于 md5 加密解密。

libmscgen 目录

是第三方库 mscgen 的源码， mscgen 库官方( https://www.mcternan.me.uk/mscgen )已经没有在维护了。

Mscgen是一个小程序，它解析消息序列图描述，并生成PNG、SVG、EPS或服务器端图像映射（ismaps）作为输出。消息序列图（MSC）是表示一段时间内实体和交互的一种方式，通常与SDL结合使用。MSC在电信中很流行，用于指定协议的操作方式，尽管创建或使用MSC并不需要复杂。Mscgen旨在提供一种简单的文本语言，该语言易于创建、编辑和理解，也可以转换为常见的图像格式进行显示或打印。

该程序及其解析的语言受到Graphviz Dot的启发，它提供了一种非常好的方法来记录状态转换图、数据结构和有向图。与Graphviz不同，该程序不进行巧妙的布局操作或样条线路由，因为MSC不需要这样做，因此实现起来要简单得多。Doxygen（1.5.2版以后的版本）还允许直接嵌入MSC

mscgen 依赖于 png 编解码库， doxygen 则使用 lodepng 这个简易的 png 编解码库替代原本的厚重的 libpng。

spdlog 目录

doxygen 原本的 log 打印是自行实现的， 估计觉得维护的太麻烦了， 4个月前切换到了 spdlog 库， 这个目录存放了 spdlog 的源代码

 Dimitri van Heesch, 4个月前   (1 15th, 2023 3:26 凌晨) 

Replace custom tracing/debug prints by tracing via spdlog

Add -t <file> option to redirect tracing to a file.
If <file> is omitted, trace.txt will be used as file name.

svg 目录

用来生成 svg.min.js 文件的， 依赖了 svgdotjs(3.1.2) 和 svgpan-1.2mod.js(1.2). mod 意思是魔改的， 改的很多， 所以不要想升级 svgpan 了， 改的特别多。

TinyDeflate 目录

是一个轻量级第三方库， 只有一个文件 gunzip.hh(C++ header-only库), 作者是 Joel Yliluoma， 用于 gzip 格式的解压， 不依赖 zlib 库。

TinyDeflate 库是收到第13届 IOCCC 获胜程序（作者 Ron McFarland）的启发和影响而写成的， 然后从 tinf 库作者 Joergen Ibsen 得到了优化方面的想法。

doc 目录

doxygen 自身的文档。从目录结构可以看出来作者本身是怎样用 doxygen 的：手写配置文件 Doxyfile。
内容较多， 可以用 doxygen 生成文档再查看； 其实应该就是 doxygen 官网的内容。略。

doc_internal 目录

内部文档， 应该是面向开发者的：

• commands_history.md: doxygen 的特殊命令（如\\#, \\date）清单， 以及是在哪个版本引入的
• commands_internal.md: doxygen 的内部的特殊命令清单
• doxygen.md: doxygen 开发者文档的介绍页
• releases.md: 历史发布版本的日期记录
• tags_history.md: doxygen 配置文件中的参数（如HTML_OUTPUT）清单， 以及是在哪个版本引入的

examples 目录

是一个例子工程， 相当于用户自己的 C/C++ 工程， 用于生成 doxygen 文档的。

libversion 目录

Doxygen 作者 Dimitri van Heesch 实现的库， 用户获取 doxygen 相关的三个版本字符串:

• const char *getDoxygenVersion(void)
• const char *getGitVersion(void);
• const char *getFullVersion(void);

libxml 目录

Doxygen 作者 Dimitri van Heesch 实现的库， 是一个基于 flex 库的 XML 文件的 parser， 代码很简单只有500行。

xml.h 是 C++ 实现的.
xml.l 是一个 flex 文件， 用 flex 生成 xml.cpp。

src 目录

doxygen 代码本体。没有子目录， 只有平铺的文件； 有 flex 文件(*.l), C/C++ 文件(*.h, *.cpp, *.c), 有 python 文件(*.py). 还有一堆翻译文件(translator_xx.h). 其中中文的翻译文件2000多行， 可以截取一点看下:

class TranslatorChinese : public TranslatorAdapter_1_9_4
{
    ...
    virtual QCString latexLanguageSupportCommand()
    {
      return "\\usepackage{CJKutf8}\n";
    }
    virtual QCString trISOLang()
    {
      return "zh";
    }
    virtual QCString getLanguageString()
    {
      return "0x804 Chinese (PRC)";
    }
    virtual QCString latexFontenc()
    {
      return "";
    }
    virtual QCString latexDocumentPre()
    {
      return "\\begin{CJK}{UTF8}{gbsn}\n";
    }
    virtual QCString latexDocumentPost()
    {
      return "\\end{CJK}\n";
    }
    virtual bool needsPunctuation()
    {
      return false;
    }


    ...

    /*! used in the compound documentation before a list of related functions.
     */
    virtual QCString trRelatedFunctions()
    { return "相关函数"; }

    /*! subscript for the related functions. */
    virtual QCString trRelatedSubscript()
    { return "(请注意: 这些不是成员函数.)"; }

    /*! header that is put before the detailed description of files,
     * classes and namespaces.
     */
    virtual QCString trDetailedDescription()
    { return "详细描述"; }

    /*! header that is used when the summary tag is missing inside the details tag */
    virtual QCString trDetails()
    { return "详细信息"; }

    /*! header that is put before the list of typedefs. */
    virtual QCString trMemberTypedefDocumentation()
    { return "成员类型定义说明"; }

    /*! header that is put before the list of enumerations. */
    virtual QCString trMemberEnumerationDocumentation()
    { return "成员枚举类型说明"; }

    /*! header that is put before the list of member function. */
    virtual QCString trMemberFunctionDocumentation()
    { return "成员函数说明"; }

    /*! header that is put before the list of member attributes. */
    virtual QCString trMemberDataDocumentation()
    {
      if (Config_getBool(OPTIMIZE_OUTPUT_FOR_C))
      {
        return "结构体成员变量说明";
      }
      else
      {
        return "类成员变量说明";
      }
    }

    /*! this is the text of a link put after brief descriptions. */
    virtual QCString trMore()
    { return "更多..."; }

    /*! put in the class documentation */
    virtual QCString trListOfAllMembers()
    { return "所有成员列表"; }

    /*! used as the title of the "list of all members" page of a class */
    virtual QCString trMemberList()
    { return "成员列表"; }

    /*! this is the first part of a sentence that is followed by a class name */
    virtual QCString trThisIsTheListOfAllMembers()
    { return "成员的完整列表，这些成员属于" CN_SPC; }

    /*! this is the remainder of the sentence after the class name */
    virtual QCString trIncludingInheritedMembers()
    { return ",包括所有继承而来的类成员"; }

    /*! this is put at the author sections at the bottom of man pages.
     *  parameter s is name of the project name.
     */
    virtual QCString trGeneratedAutomatically(const QCString &s)
    { QCString result;
      result = "由" CN_SPC "Doyxgen" CN_SPC "通过分析" CN_SPC;
      if (!s.isEmpty()) result += (s+CN_SPC "的" CN_SPC);
      result+= "源代码自动生成.";
      return result;
    }

    ...
};

templates 目录

templates 意思是模板， 这个目录存放了几个子目录， 对应不同类别的模板:

• general
• html
• icon
• latex
• xml

general 目录

通用的模板， 给出了默认的布局 xml 文件。

html 目录

猜测是 doxygen 生成的 html 格式文档的模板。文件比较多， 几十个。

icon 目录

doxygen 的图标（icon）。

latex 目录

latex 模板。文件相对来说比较少。因为 latex 最终输出是 pdf 单个文件， 不像 html 那样一箩筐。

xml 目录

存放了几个 xsd 文件。

XSD 文件是一个定义文件，它指定可以成为 XML 文档的一部分的元素和属性。这可确保正确解释数据并捕获错误，从而进行适当的 XML 验证。 XSD 文件确保输入的数据遵循文件中定义的相同结构。 XSD 文件以 XML 文件格式存储

testing 目录

放了101个子目录， 每个目录对应一份测试数据。测试数据是 xml格式的。

除了101个子目录， 每个目录都有一个配套的文件， 如 c, cpp, dox 文件。

101个子目录应该是预期输出的内容（ground truth， EXPECTED RESULT）.

vhdlparser 目录

解析 vhdl 的代码实现。VHDL全名Very-High-Speed Integrated Circuit Hardware Description Language， 是一种用于电路设计的高级语言。

winbuild 目录

存放在 Windows 系统上编译 doxygen 库时， 需要的 iconv 库。 iconv 库本体是 GNU 下开发的， 不支持 Windows。 有网友修改移植了 iconv 库， 之前有创建 Release， 后来估计删除了， 因此 doxygen 的 gitlab CI 中从 release 下载的step其实现在无效了。