Doxygen源码分析: 根目录文件简要介绍

2023-05-18 22:54:02
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

zz@Legion-R7000P% tree -L 1
.
├── addon
├── BUILD.txt
├── cmake
├── CMakeLists.txt
├── deps
├── doc
├── doc_internal
├── Dockerfile
├── examples
├── INSTALL
├── LANGUAGE.HOWTO
├── libversion
├── libxml
├── LICENSE
├── README.md
├── src
├── templates
├── testing
├── VERSION
├── vhdlparser
└── winbuild

13 directories, 8 files

2. 文件介绍

列出根目录所有文件, 总计12个

zz@Legion-R7000P% find . -maxdepth 1 -type f
./Dockerfile
./LICENSE
./.dockerignore
./.codedocs
./VERSION
./.editorconfig
./LANGUAGE.HOWTO
./BUILD.txt
./INSTALL
./.gitignore
./README.md
./CMakeLists.txt

zz@Legion-R7000P% find . -maxdepth 1 -type f | wc -l
12

Dockerfile

给出了 Linux 下的编译环境， 免去用户手动配置环境。

LICENSE

用的是 GPLv2 协议。

.dockerignore

docker 忽略文件的配置文件。

.codedocs

bing上没找到搜索结果，看起来像是类似 doxygen 的配置文件 Doxyfile 的一个文件， EXCLUDE 是忽略的目录和文件，FILE_PATTERNS 是需要生成文档（被扫描）的文件模式。

VERSION

存放了 doxygen 的版本号， 当前版本为 1.9.7。

.editorconfig

是 EditorConfig 的配置文件， 配置为： 所有文件默认用2空格缩进， Python 文件则用4空格缩进。

LANGUAGE.HOWTO

给出了在 doxygen 中新添加一门语言支持（翻译）的简要步骤， 这里的语言指的是自然语言，如英语，中文等。

1. 给出语言的名称。

2. 编辑 src/config.xml

• 寻找 <option>， 找到其中 id='OUTPUT_LANGUAGE 的那一个
• 使用你想添加的语言， 添加一个新的值

3. 基于 translator_en.h， 拷贝、改文件名。我们用 translator_xx.h 表示这个具体的文件。

4. 编辑 language.cpp

• 添加头文件包含:

  #include "translator_xx.h"
  

• 在 setTranslator() 中添加:

           case OUTPUT_LANGUAGE_t::YourLanguage: theTranslator = new TranslatorYourLanguage; break;
  

5. 编辑 translator_xx.h:

• 修改 TRANSLATOR_EN_H 为 TRANSLATOR_XX_H (#include 和 #define 都改)
• 修改 TranslatorEnglish 为 TranslatorYourLanguage
• 在成员函数 idLanguage() 中， 修改 “english” 为你的语言（只允许小写字母）。设置 trISOLang() 和 getLanguageString() 返回值为你的语言。
  根据实际清情况， 你可能还想修改 latexLanguageSupportCommand()
• 编辑所有以 tr 开头的成员函数里的返回值。注意大小写和标点符号。
  为了输入特殊字符（包括重音），你需要：
  a) 用 UTF-8 编码
  b) 可以直接写， 也可以用 html 代码例如 &auml 来表示 umlaut (也就是 ä)

6. 重新构建整个工程, 例如

   cd path/where/you/build
   cmake --build .
   

7. 现在可以在 Doxygen 的配置文件中使用 OUTPUT_LANGUAGE = 你的语言 了

8. 发送 translator_xx.h 给 Doxygen 作者， 这样他可以添加到 Doxygen 代码主仓库。

BUILD.txt

给出了构建（编译+链接+安装）整个工程的一些指导建议。

Doxygen 使用 cmake 构建工程， 支持多个平台。 具体怎么用 cmake 就略过了。

Doxygen 的 cmake 提供了如下 option:

option	解释
build_wizard	构建 doxygen 的 GUI 前端
build_app	例子工程， 展示了怎样嵌入 doxygen 到一个应用程序中
build_parse	转换源代码并且打印出代码元素之间的依赖关系
build_xmlparser	例子工程， 展示了怎样解析 doxygen 的 XML 输出
build_search	构建外部的搜索工具（doxysearch 和 doxyindexer）
build_doc	构建用户手册
use_sqlite3	增加 sqlite3 输出的支持（实验性质）
use_libclang	增加 libclang 解析的支持
win_static	在 Windows 上使用 /MT 的 CRT， 替代 /MD
force_qt=<vers>	强制doxywizard使用指定的主要版本进行构建，这可以是Qt5或Qt6

可以使用 cmake 的 -L 参数打印这些 option 的取值:

cmake -L path/to/root/of/doxygen/source/tree

INSTALL

内容很简单， 安装步骤请具体查看在线网页 https://www.doxygen.nl/manual/install.html

.gitignore

从 gitignore 文件可以看出作者的一些编程习惯:

*~
.*sw?
\#*
.DS_Store

作者是用 vim 开发的， 并且处理了 mac 系统的 DS_Store 文件。

tags

.idea

/examples/html/*
/examples/latex/*

examplels 目录看来是日常调试验证用的， 子目录 html 和 latex 直接被忽略的。

README.md

doxygen 有三个作用：

1. 它可以生成在线文档浏览器（HTML）和/或离线参考手册（LaTeX），来自一组文档化的源文件。
   还支持生成RTF（MS Word）、PostScript等格式的输出，超链接PDF、压缩HTML、DocBook和Unix手册页。
   文档是直接从来源中提取的，这使得使文档与源代码保持一致要容易得多。

2. 您可以配置doxygen来从未记录的代码中提取代码结构源文件。这对快速找到你的路非常有用
   源分布。Doxygen还可以可视化通过包括依赖关系图、继承等方式的各种元素图和协作图，它们都是自动生成的。

3. 您也可以使用doxygen来创建普通文档（就像作者为doxygen用户手册和doxygen网站）。

doxygen 在 2013 年以前是用 svn 的， 2013 年则迁移到 git， 并在 github 上托管代码。

Doxygen 作者是 Dimitri van Heesch.

CMakeLists.txt

这是整个工程构建的入口描述文件， 代码有230行， 需要配合各个子目录的构建文件 （例如 src/CMakeLists.txt）才可以弄清楚， 因此本篇略过， 留作下一篇处理。