Doxygen源码分析：doxygen执行过程的拆解
2023-05-19 23:09:17 ~ 2023-05-20 16:38:13
ChrisZZ imzhuo@foxmailcom
Hompage https://github.com/zchrissirhcz
文章目录
1. doxygen 版本
本次使用的 doxygen 版本如下, 相比于前几篇源码分析时用的版本，有更新，对应到 doxygen 正式版1.9.8（没有特别大的变化）：
$ git log
commit 5fded4215d4f9271fe92c940fc4532d4704f5be1 (HEAD -> master, upstream/master)
Author: Dimitri van Heesch <doxygen@gmail.com>
Date: Thu May 18 22:14:30 2023 +0200
bump version to 1.9.8 for development
2. doxygen 可执行程序的入口: src/main.cpp
在 src/CMakeLists.txt 中看到 doxygen 这个 target 的描述, 它由 main.cpp 和 doxygen.rc 两个文件组成：
add_executable(doxygen
main.cpp
${PROJECT_SOURCE_DIR}/templates/icon/doxygen.rc
)
doxygen.rc 不是代码， 忽略； main.cpp 给出了整个 doxygen 执行的6部分内容：
#include "doxygen.h"
/*! \file
* \brief main entry point for doxygen
*
* This file contains main()
*/
/*! Default main. The idea of separating this from the rest of doxygen,
* is to make it possible to write your own main, with a different
* generateOutput() function for instance.
*/
int main(int argc,char **argv)
{
initDoxygen(); // 初始化 doxygen
readConfiguration(argc,argv); // 读取配置， 通常是读取 Doxyfile 这一配置文件
checkConfiguration(); // 检查和解析配置选项
adjustConfiguration(); // 调整配置：有些全局变量依赖于配置
parseInput(); // 解析输入
generateOutput(); // 生成输出， 例如 html, xml, latex, pdf
return 0;
}
3. initDoxygen(): 初始化 doxygen 的过程浅析
包括如下部分：
- 初始化资源：加载 templates 目录下的文件
- 设置语言、编码等本地化的配置
- 检查和修正路径
- 调试工具的计时器开始计时
- 给各编程语言注册 parser
- 为 LinkedMap 类的子类实例执行初始化：成员名字、函数名字、namespace、class 等
- 其他全局配置的初始化
以下是包含注释的 initDoxygen() 函数源码:
// src/doxyge.cpp, L10724-L10803
void initDoxygen()
{
initResources(); // 初始化资源， 在 build/generated_src/resources.cpp 里实现， 把 templates 目录下的每个文件都注册进来
QCString lang = Portable::getenv("LC_ALL"); // QCString 是 doxygen 中重新实现的， 接口和 Qt 的 QCString 保持一致。内部使用 std::string.
if (!lang.isEmpty()) Portable::setenv("LANG",lang); // 设置语言，编码等
std::setlocale(LC_ALL,"");
std::setlocale(LC_CTYPE,"C"); // to get isspace(0xA0)==0, needed for UTF-8
std::setlocale(LC_NUMERIC,"C");
Doxygen::symbolMap = new SymbolMap<Definition>; // SymbolMap 是模板类， 把符号名字映射为对象。 Definition 是所有定义实体（类，成员函数，文件，作用域等）的公共基类
Portable::correct_path(); // Portable 是一个 namespace， 提供了跨平台的函数， 如 sysmtem(), pid,(), getenv(), sleep(), isAbsolutePath() 等。
// correct_path() 用于修正一个可能错误的路径，例如在 MSVC 编译器下, 把路径中的 "/" 替换为 "\\"
Debug::startTimer(); // 开启全局计时器。 Debug 是一个类， 包含了打印函数 print(), 用于调试。
// ParserManger 管理各种编程语言的解析器，提供注册 parser、根据文件扩展获取 parser 的功能。
// 默认注册的语言是： C, Python, Fortran, FortranFree, FortranFixed, VHDL, XML, SQL, Markdown, Lex
Doxygen::parserManager = new ParserManager( make_parser_factory<NullOutlineParser>(),
make_parser_factory<FileCodeParser>());
Doxygen::parserManager->registerParser("c", make_parser_factory<COutlineParser>(),
make_parser_factory<CCodeParser>());
Doxygen::parserManager->registerParser("python", make_parser_factory<PythonOutlineParser>(),
make_parser_factory<PythonCodeParser>());
Doxygen::parserManager->registerParser("fortran", make_parser_factory<FortranOutlineParser>(),
make_parser_factory<FortranCodeParser>());
Doxygen::parserManager->registerParser("fortranfree", make_parser_factory<FortranOutlineParserFree>(),
make_parser_factory<FortranCodeParserFree>());
Doxygen::parserManager->registerParser("fortranfixed", make_parser_factory<FortranOutlineParserFixed>(),
make_parser_factory<FortranCodeParserFixed>());
Doxygen::parserManager->registerParser("vhdl", make_parser_factory<VHDLOutlineParser>(),
make_parser_factory<VHDLCodeParser>());
Doxygen::parserManager->registerParser("xml", make_parser_factory<NullOutlineParser>(),
make_parser_factory<XMLCodeParser>());
Doxygen::parserManager->registerParser("sql", make_parser_factory<NullOutlineParser>(),
make_parser_factory<SQLCodeParser>());
Doxygen::parserManager->registerParser("md", make_parser_factory<MarkdownOutlineParser>(),
make_parser_factory<FileCodeParser>());
Doxygen::parserManager->registerParser("lex", make_parser_factory<LexOutlineParser>(),
make_parser_factory<LexCodeParser>());
// register any additional parsers here...
// 初始化默认的扩展映射： 把文件的扩展名（如 .hpp） 映射到 parser（如parser id 为 "c"）
initDefaultExtensionMapping();
// doxygen 默认没开启 libclang. 用户可手动开启， 开启后会使用 clang parser 以获得更准确的解析结果, 不过速度会慢
// USE_LIBCLANG 适合大量使用了 C++ 模板的代码（的工程中的文档生成）， doxygen 内置的 parser 对必要的类型信息比较缺乏。
#if USE_LIBCLANG
Doxygen::clangUsrMap = new ClangUsrMap;
#endif
Doxygen::memberNameLinkedMap = new MemberNameLinkedMap; // MemberNameLinkedMap 类是 “成员名字对象”的有序字典类. 是 LinkedMap<MemberName>
Doxygen::functionNameLinkedMap = new MemberNameLinkedMap; // MemberNameLinkedMap 类是 LinkedMap<MemberName>
Doxygen::groupLinkedMap = new GroupLinkedMap; // GroupLinkedMap 类是 LinkedMap<GroupDef>
Doxygen::namespaceLinkedMap = new NamespaceLinkedMap; // NamespaceLinkedMap 类是 LinkedMap<NamespaceDef>
Doxygen::classLinkedMap = new ClassLinkedMap; // ClassLinkedMap 类是 LinkedMap<ClassDef>
Doxygen::hiddenClassLinkedMap = new ClassLinkedMap;
Doxygen::conceptLinkedMap = new ConceptLinkedMap; // ConceptLinkedMap 类是 LinkedMap<ConceptDef>
Doxygen::dirLinkedMap = new DirLinkedMap; // DirLinkedMap 类是 LinkedMap<DirDef>
Doxygen::pageLinkedMap = new PageLinkedMap; // all doc pages // PageLinkedMap 类是 LinkedMap<PageDef>
Doxygen::exampleLinkedMap = new PageLinkedMap; // all examples
//Doxygen::tagDestinationDict.setAutoDelete(TRUE);
Doxygen::indexList = new IndexList; // 索引接口列表类
// initialisation of these globals depends on
// configuration switches so we need to postpone these
// 如下全局变量的值，可以在配置文件中覆盖，此处仅做默认值的赋值
// 实际上它们都是空指针， 使用 nullptr 替代 0 更合适
Doxygen::globalScope = 0;
Doxygen::inputNameLinkedMap = 0;
Doxygen::includeNameLinkedMap = 0;
Doxygen::exampleNameLinkedMap = 0;
Doxygen::imageNameLinkedMap = 0;
Doxygen::dotFileNameLinkedMap = 0;
Doxygen::mscFileNameLinkedMap = 0;
Doxygen::diaFileNameLinkedMap = 0;
/**************************************************************************
* Initialize some global constants
**************************************************************************/
// g_compoundKeywords 是一个 set, 基本元素是 string
g_compoundKeywords.insert("template class");
g_compoundKeywords.insert("template struct");
g_compoundKeywords.insert("class");
g_compoundKeywords.insert("struct");
g_compoundKeywords.insert("union");
g_compoundKeywords.insert("interface");
g_compoundKeywords.insert("exception");
}
4. readConfiguration(argc, argv): 读取配置文件的过程浅析
- 获取 doxygen 版本信息
- 定义
writeFile()函数 - 解析 argv 参数
- …
直接看这个函数的源码， 不是很容易连贯起来， 可以直接从 doxygen --help 给出的整段提示内容得到启发，再结合源码可以得到更好的理解:
zz@Legion-R7000P% doxygen --help
Doxygen version 1.9.8 (5fded4215d4f9271fe92c940fc4532d4704f5be1*)
Copyright Dimitri van Heesch 1997-2021
You can use doxygen in a number of ways:
1) Use doxygen to generate a template configuration file*:
doxygen [-s] -g [configName]
2) Use doxygen to update an old configuration file*:
doxygen [-s] -u [configName]
3) Use doxygen to generate documentation using an existing configuration file*:
doxygen [configName]
4) Use doxygen to generate a template file controlling the layout of the
generated documentation:
doxygen -l [layoutFileName]
In case layoutFileName is omitted DoxygenLayout.xml will be used as filename.
If - is used for layoutFileName doxygen will write to standard output.
5) Use doxygen to generate a template style sheet file for RTF, HTML or Latex.
RTF: doxygen -w rtf styleSheetFile
HTML: doxygen -w html headerFile footerFile styleSheetFile [configFile]
LaTeX: doxygen -w latex headerFile footerFile styleSheetFile [configFile]
6) Use doxygen to generate a rtf extensions file
doxygen -e rtf extensionsFile
If - is used for extensionsFile doxygen will write to standard output.
7) Use doxygen to compare the used configuration file with the template configuration file
doxygen -x [configFile]
Use doxygen to compare the used configuration file with the template configuration file
without replacing the environment variables or CMake type replacement variables
doxygen -x_noenv [configFile]
8) Use doxygen to show a list of built-in emojis.
doxygen -f emoji outputFileName
If - is used for outputFileName doxygen will write to standard output.
*) If -s is specified the comments of the configuration items in the config file will be omitted.
If configName is omitted 'Doxyfile' will be used as a default.
If - is used for configFile doxygen will write / read the configuration to /from standard output / input.
If -q is used for a doxygen documentation run, doxygen will see this as if QUIET=YES has been set.
-v print version string, -V print extended version information
-h,-? prints usage help information
doxygen -d prints additional usage flags for debugging purposes
带注释的 readConfiguration(argc, argv) 代码如下：
// src/doxygen.cpp, L10847-L11248
void readConfiguration(int argc, char **argv)
{
// getFullVersion() 在 libversion/fullversion.cpp 中实现， 结果形如 1.9.8 (git commit id)
// 其中获取 git commit id 是在 build/generated_src/gitversion.cpp 的 getGitVersion() 函数实现的
QCString versionString = getFullVersion();
// helper that calls \a func to write to file \a fileName via a TextStream
// writeFile 是一个 把 TextStream 写入文件的 lambda 函数。
// TextStream 类是 std::ostringstream 类的改进版， 更简单，性能也更高
auto writeFile = [](const char *fileName,std::function<void(TextStream&)> func) -> bool
{
std::ofstream f;
if (openOutputFile(fileName,f))
{
TextStream t(&f);
func(t);
return true;
}
return false;
};
/**************************************************************************
* Handle arguments *
**************************************************************************/
// 解析 argv[1]...argv[argc-1] 参数。对于每个 argv[i] 来说， 需要 argv[i][0] 为 '-', argv[i][1] 为具体的选项（单个字母）
// 例如， doxygen -g 其中 g 表示要生成（generate）配置文件
int optInd=1;
QCString configName;
QCString layoutName;
QCString debugLabel;
QCString formatName;
QCString listName;
QCString traceName;
bool genConfig=FALSE;
bool shortList=FALSE;
Config::CompareMode diffList=Config::CompareMode::Full;
bool updateConfig=FALSE;
int retVal;
bool quiet = false;
while (optInd<argc && argv[optInd][0]=='-' &&
(isalpha(argv[optInd][1]) || argv[optInd][1]=='?' ||
argv[optInd][1]=='-')
)
{
switch(argv[optInd][1])
{
case 'g': // g = generate, 生成配置文件
genConfig=TRUE;
break;
case 'l': // l = layout, 指定 xml 布局文件
if (optInd+1>=argc)
{
layoutName="DoxygenLayout.xml";
}
else
{
layoutName=argv[optInd+1];
}
writeDefaultLayoutFile(layoutName);
cleanUpDoxygen();
exit(0);
break;
case 'd': // d = debug, 生成调试标签。给 doxygen 开发者用的。
debugLabel=getArg(argc,argv,optInd);
if (debugLabel.isEmpty())
{
devUsage();
cleanUpDoxygen();
exit(0);
}
retVal = Debug::setFlagStr(debugLabel);
if (!retVal)
{
err("option \"-d\" has unknown debug specifier: \"%s\".\n",qPrint(debugLabel));
devUsage();
cleanUpDoxygen();
exit(1);
}
break;
case 't': // t = tracing, 开启开发 log
{
#if ENABLE_TRACING
if (optInd+1>=argc || argv[optInd+1][0] == '-')
{
traceName="trace.txt";
}
else
{
traceName=argv[optInd+1];
optInd++;
}
#else
err("support for option \"-t\" has not been compiled in (use a debug build or a release build with tracing enabled).\n");
cleanUpDoxygen();
exit(1);
#endif
}
break;
case 'x': // x = compare，意思是比较当前实用的配置文件和模板中的配置文件。类型定义位于 src/config.h 中的 config::CompareMode 类。
if (!strcmp(argv[optInd]+1,"x_noenv")) diffList=Config::CompareMode::CompressedNoEnv;
else if (!strcmp(argv[optInd]+1,"x")) diffList=Config::CompareMode::Compressed;
else
{
err("option should be \"-x\" or \"-x_noenv\", found: \"%s\".\n",argv[optInd]);
cleanUpDoxygen();
exit(1);
}
break;
case 's': // s = shortlist, 含义暂时不明
shortList=TRUE;
break;
case 'u': // u = update config, 更新配置文件
updateConfig=TRUE;
break;
case 'e': // e = extension, 用于生成 RTF 扩展文件， 例如 doxygen -e rtf extensionsFile
formatName=getArg(argc,argv,optInd);
if (formatName.isEmpty())
{
err("option \"-e\" is missing format specifier rtf.\n");
cleanUpDoxygen();
exit(1);
}
if (qstricmp(formatName.data(),"rtf")==0)
{
if (optInd+1>=argc)
{
err("option \"-e rtf\" is missing an extensions file name\n");
cleanUpDoxygen();
exit(1);
}
writeFile(argv[optInd+1],RTFGenerator::writeExtensionsFile);
cleanUpDoxygen();
exit(0);
}
err("option \"-e\" has invalid format specifier.\n");
cleanUpDoxygen();
exit(1);
break;
case 'f': // f = filename, 显示 doxygen 内置的 emoji， 并打印输出到文件
listName=getArg(argc,argv,optInd);
if (listName.isEmpty())
{
err("option \"-f\" is missing list specifier.\n");
cleanUpDoxygen();
exit(1);
}
if (qstricmp(listName.data(),"emoji")==0)
{
if (optInd+1>=argc)
{
err("option \"-f emoji\" is missing an output file name\n");
cleanUpDoxygen();
exit(1);
}
writeFile(argv[optInd+1],[](TextStream &t) { EmojiEntityMapper::instance().writeEmojiFile(t); });
cleanUpDoxygen();
exit(0);
}
err("option \"-f\" has invalid list specifier.\n");
cleanUpDoxygen();
exit(1);
break;
case 'w': // w = ? , 让 doxygen 为 RTF, HTML or Latex 输出生成样式文件
formatName=getArg(argc,argv,optInd);
if (formatName.isEmpty())
{
err("option \"-w\" is missing format specifier rtf, html or latex\n");
cleanUpDoxygen();
exit(1);
}
if (qstricmp(formatName.data(),"rtf")==0)
{
if (optInd+1>=argc)
{
err("option \"-w rtf\" is missing a style sheet file name\n");
cleanUpDoxygen();
exit(1);
}
if (!writeFile(argv[optInd+1],RTFGenerator::writeStyleSheetFile))
{
err("error opening RTF style sheet file %s!\n",argv[optInd+1]);
cleanUpDoxygen();
exit(1);
}
cleanUpDoxygen();
exit(0);
}
else if (qstricmp(formatName.data(),"html")==0)
{
Config::init();
if (optInd+4<argc || FileInfo("Doxyfile").exists())
// explicit config file mentioned or default found on disk
{
QCString df = optInd+4<argc ? argv[optInd+4] : QCString("Doxyfile");
if (!Config::parse(df)) // parse the config file
{
err("error opening or reading configuration file %s!\n",argv[optInd+4]);
cleanUpDoxygen();
exit(1);
}
}
if (optInd+3>=argc)
{
err("option \"-w html\" does not have enough arguments\n");
cleanUpDoxygen();
exit(1);
}
Config::postProcess(TRUE);
Config::updateObsolete();
Config::checkAndCorrect(Config_getBool(QUIET), false);
setTranslator(Config_getEnum(OUTPUT_LANGUAGE));
writeFile(argv[optInd+1],[&](TextStream &t) { HtmlGenerator::writeHeaderFile(t,argv[optInd+3]); });
writeFile(argv[optInd+2],HtmlGenerator::writeFooterFile);
writeFile(argv[optInd+3],HtmlGenerator::writeStyleSheetFile);
cleanUpDoxygen();
exit(0);
}
else if (qstricmp(formatName.data(),"latex")==0)
{
Config::init();
if (optInd+4<argc || FileInfo("Doxyfile").exists())
{
QCString df = optInd+4<argc ? argv[optInd+4] : QCString("Doxyfile");
if (!Config::parse(df))
{
err("error opening or reading configuration file %s!\n",argv[optInd+4]);
cleanUpDoxygen();
exit(1);
}
}
if (optInd+3>=argc)
{
err("option \"-w latex\" does not have enough arguments\n");
cleanUpDoxygen();
exit(1);
}
Config::postProcess(TRUE);
Config::updateObsolete();
Config::checkAndCorrect(Config_getBool(QUIET), false);
setTranslator(Config_getEnum(OUTPUT_LANGUAGE));
writeFile(argv[optInd+1],LatexGenerator::writeHeaderFile);
writeFile(argv[optInd+2],LatexGenerator::writeFooterFile);
writeFile(argv[optInd+3],LatexGenerator::writeStyleSheetFile);
cleanUpDoxygen();
exit(0);
}
else
{
err("Illegal format specifier \"%s\": should be one of rtf, html or latex\n",qPrint(formatName));
cleanUpDoxygen();
exit(1);
}
break;
case 'm': // m = map, 导出符号映射文件
g_dumpSymbolMap = TRUE;
break;
case 'v': // v = version, 用 msg() 打印版本信息， false 表示不要打印扩展的版本信息内容（如sqlite, libclang等）
version(false);
cleanUpDoxygen();
exit(0);
break;
case 'V': // V = version, 打印常规的版本信息之外， 还打印扩展的版本信息内容
version(true);
cleanUpDoxygen();
exit(0);
break;
case '-':
if (qstrcmp(&argv[optInd][2],"help")==0) // --help 打印帮助信息
{
usage(argv[0],versionString);
exit(0);
}
else if (qstrcmp(&argv[optInd][2],"version")==0) // --version 打印版本信息
{
version(false);
cleanUpDoxygen();
exit(0);
}
else if ((qstrcmp(&argv[optInd][2],"Version")==0) ||
(qstrcmp(&argv[optInd][2],"VERSION")==0)) // --Version 和 --VERSION 打印版本信息
{
version(true);
cleanUpDoxygen();
exit(0);
}
else
{
err("Unknown option \"-%s\"\n",&argv[optInd][1]);
usage(argv[0],versionString);
exit(1);
}
break;
case 'b': // b = buf, 指定IO流的缓冲区群， `_IONBF` 意思是“不使用缓冲区”，因此会立即输出到控制台
setvbuf(stdout,NULL,_IONBF,0);
break;
case 'q': // q = quiet, 安静模式
quiet = true;
break;
case 'T': // T = template, 意思是使用 Django 风格的模板文件。目前还处于实验状态， 请谨慎使用。
msg("Warning: this option activates output generation via Django like template files. "
"This option is scheduled for doxygen 2.0, is currently incomplete and highly experimental! "
"Only use if you are a doxygen developer\n");
g_useOutputTemplate=TRUE;
break;
case 'h': // -h 和 -? : 打印用法
case '?':
usage(argv[0],versionString);
exit(0);
break;
default:
err("Unknown option \"-%c\"\n",argv[optInd][1]);
usage(argv[0],versionString);
exit(1);
}
optInd++;
}
/**************************************************************************
* Parse or generate the config file *
**************************************************************************/
// 解析或生成配置文件
initTracing(traceName.data());
TRACE("Doxygen version used: {}",getFullVersion());
Config::init();
FileInfo configFileInfo1("Doxyfile"),configFileInfo2("doxyfile");
if (optInd>=argc)
{
if (configFileInfo1.exists())
{
configName="Doxyfile";
}
else if (configFileInfo2.exists())
{
configName="doxyfile";
}
else if (genConfig)
{
configName="Doxyfile";
}
else
{
err("Doxyfile not found and no input file specified!\n");
usage(argv[0],versionString);
exit(1);
}
}
else
{
FileInfo fi(argv[optInd]);
if (fi.exists() || qstrcmp(argv[optInd],"-")==0 || genConfig)
{
configName=argv[optInd];
}
else
{
err("configuration file %s not found!\n",argv[optInd]);
usage(argv[0],versionString);
exit(1);
}
}
if (genConfig && g_useOutputTemplate)
{
generateTemplateFiles("templates");
cleanUpDoxygen();
exit(0);
}
if (genConfig)
{
generateConfigFile(configName,shortList);
cleanUpDoxygen();
exit(0);
}
if (!Config::parse(configName,updateConfig,diffList))
{
err("could not open or read configuration file %s!\n",qPrint(configName));
cleanUpDoxygen();
exit(1);
}
if (diffList!=Config::CompareMode::Full)
{
Config::updateObsolete();
compareDoxyfile(diffList);
cleanUpDoxygen();
exit(0);
}
if (updateConfig)
{
Config::updateObsolete();
generateConfigFile(configName,shortList,TRUE);
cleanUpDoxygen();
exit(0);
}
/* Perlmod wants to know the path to the config file.*/
FileInfo configFileInfo(configName.str());
setPerlModDoxyfile(configFileInfo.absFilePath());
/* handle -q option */
if (quiet) Config_updateBool(QUIET,TRUE);
}
查看 doxygen 内置的 emoji
doxygen -f emoji doxygen-emoji.md
然后用 VSCode 的 markdown 预览查看：
开启 Tracing
需要在 cmake 构建阶段传入参数 -D enable_tracing, 或指定构建类型-D CMAKE_BUILD_TYPE=Debug, 这样可以开启 ENABLE_TRACING 宏定义。e.g.
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/home/zz/soft/doxygen -Denable_tracing=ON
cmake --build build -j14
cmake --build build -j14 --target install
还需要在执行 doxygen 时， 传入 -t 参数:
# 假设当前路径下已经有 Doxyfile 了
# 如下是正确的三种调用方式
doxygen -t # 会开启 trace, 并记录在名为 trace.txt 的文件中
doxygen -t mytrace.txt # 会开启 trace, 并记录在名为 trace.txt 的文件中
doxygen -t mytrace.txt Doxyfile # 会开启 trace, 并记录在名为 mytrace.txt 的文件中
# 如下是错误的三种调用方式
doxygen # 不会开启 trace
doxygen Doxyfile # 不会开启 trace
doxygen Doxxyfile -t mytrace.txt # 不会开启 trace
doxygen -t Doxyfile # 错误：会把 trace 内容输出到 Doxyfile 文件中，覆盖原有内容
5. checkConfiguration(): 检查和解析配置选项的过程浅析
代码只有10行，
/** check and resolve config options */
void checkConfiguration()
{
AUTO_TRACE(); // 如果开启了 tracing 功能， 会执行 trace
Config::postProcess(FALSE); // 配置文件的后处理， 如默认值的填充等
Config::updateObsolete(); // 更新淘汰的配置
Config::checkAndCorrect(Config_getBool(QUIET), true); // 检查和纠正配置
initWarningFormat(); // 初始化警告格式
}
6. adjustConfiguration(): 调整配置文件的过程浅析
- 设置输出文档的自然语言
- 设置输出 html 文件的后缀名字
- 判断是否需要额外的 parse ， 用于生成额外的调用依赖关系图
- 检查和处理指定的特殊 parser 映射关系（文件扩展名对应的 parser）
- 检查全局的输入文件编码配置项目， 以及单个文件级别的文件编码配置项
- 读取用户定义的宏、别名
- 读取制表符的宽度
/** adjust globals that depend on configuration settings. */
void adjustConfiguration()
{
AUTO_TRACE(); // 开启自动 tracing。 取决于编译时是否开启trace， 以及运行 doxygen 时是否传入 -t 参数
// 一些全局对象的创建。比较奇怪的是，为什么有些用 unique_ptr, 有些则还是 raw pointer.
Doxygen::globalNamespaceDef = createNamespaceDef("<globalScope>",1,1,"<globalScope>");
Doxygen::globalScope = toNamespaceDefMutable(Doxygen::globalNamespaceDef.get());
Doxygen::inputNameLinkedMap = new FileNameLinkedMap;
Doxygen::includeNameLinkedMap = new FileNameLinkedMap;
Doxygen::exampleNameLinkedMap = new FileNameLinkedMap;
Doxygen::imageNameLinkedMap = new FileNameLinkedMap;
Doxygen::dotFileNameLinkedMap = new FileNameLinkedMap;
Doxygen::mscFileNameLinkedMap = new FileNameLinkedMap;
Doxygen::diaFileNameLinkedMap = new FileNameLinkedMap;
// 设置翻译器。取决于输出的语言。
// 例如对于中文: case OUTPUT_LANGUAGE_t::Chinese: theTranslator = new TranslatorChinese; break;
setTranslator(Config_getEnum(OUTPUT_LANGUAGE));
/* Set the global html file extension. */
// 设置全局 html 文件扩展. 默认使用 .html, 也可以改为 .htm, .php, .asp 等
// https://www.doxygen.nl/manual/config.html#cfg_extension_mapping
Doxygen::htmlFileExtension = Config_getString(HTML_FILE_EXTENSION);
// 是否需要解析源代码： 需要这4个配置中至少有一个为真: CALL_GRAPH, CALLER_GRAPH, REFERENCES_RELATION, REFERENCED_BY_RELATION
// CALL_GRAPH: https://www.doxygen.nl/manual/config.html#cfg_call_graph
// 如果为真， 则doxygen将为每个全局函数或类方法生成一个调用依赖图。
// 启用此选项将显著增加运行时间。因此，在大多数情况下，最好只使用\callgraph命令为所选函数启用调用图。禁用调用图可以通过命令\hidecallgraph来完成。
// CALLER_GRAPH: https://www.doxygen.nl/manual/config.html#cfg_caller_graph
// 如果为真， 则为每个全局函数和类方法生成“谁调用了它”的依赖关系图
// REFERENCES_RELATION: https://www.doxygen.nl/manual/config.html#cfg_references_relation
// 如果为真， 则为每个被文档化的函数， 列出调用了的、使用了的函数 。（列出“它调用了谁”）
// REFERENCED_BY_RELATION: https://www.doxygen.nl/manual/config.html#cfg_referenced_by_relation
// 如果为真， 则对于每个文档化实体，将列出引用该实体的所有文档化函数。 （列出“谁调用了它”）
Doxygen::parseSourcesNeeded = Config_getBool(CALL_GRAPH) ||
Config_getBool(CALLER_GRAPH) ||
Config_getBool(REFERENCES_RELATION) ||
Config_getBool(REFERENCED_BY_RELATION);
/**************************************************************************
* Add custom extension mappings
**************************************************************************/
// 对于每一种扩展的映射的处理
// doxygen 内置了每一种扩展对应的 parser， 而使用 EXTENSION_MAPPING 则可以覆盖默认的 parser 的 mapping。
// https://www.doxygen.nl/manual/config.html#cfg_extension_mapping
const StringVector &extMaps = Config_getList(EXTENSION_MAPPING);
for (const auto &mapping : extMaps)
{
QCString mapStr = mapping.c_str();
int i=mapStr.find('=');
if (i==-1)
{
continue;
}
else
{
QCString ext = mapStr.left(i).stripWhiteSpace().lower();
QCString language = mapStr.mid(i+1).stripWhiteSpace().lower();
if (ext.isEmpty() || language.isEmpty())
{
continue;
}
if (!updateLanguageMapping(ext,language))
{
err("Failed to map file extension '%s' to unsupported language '%s'.\n"
"Check the EXTENSION_MAPPING setting in the config file.\n",
qPrint(ext),qPrint(language));
}
else
{
msg("Adding custom extension mapping: '%s' will be treated as language '%s'\n",
qPrint(ext),qPrint(language));
}
}
}
// create input file exncodings
// check INPUT_ENCODING
// 检查输入的文件编码。 用到了 iconv 库， 基于 iconv 的 API 封装实现了 portable_iconv_open()
// https://www.doxygen.nl/manual/config.html#cfg_input_encoding
void *cd = portable_iconv_open("UTF-8",Config_getString(INPUT_ENCODING).data());
if (cd==reinterpret_cast<void *>(-1))
{
term("unsupported character conversion: '%s'->'%s': %s\n"
"Check the 'INPUT_ENCODING' setting in the config file!\n",
qPrint(Config_getString(INPUT_ENCODING)),qPrint("UTF-8"),strerror(errno));
}
else
{
portable_iconv_close(cd);
}
// check and split INPUT_FILE_ENCODING
// 拆解 INPUT_FILE_ENCODING 配置项的取值. INPUT_FILE_ENCODING 允许为单个文件设置编码格式
// https://www.doxygen.nl/manual/config.html#cfg_input_file_encoding
const StringVector &fileEncod = Config_getList(INPUT_FILE_ENCODING);
for (const auto &mapping : fileEncod)
{
QCString mapStr = mapping.c_str();
int i=mapStr.find('=');
// 如果没有找到等号， 说明没给出配置项的取值。
if (i==-1)
{
continue;
}
else
{
QCString pattern = mapStr.left(i).stripWhiteSpace().lower();
QCString encoding = mapStr.mid(i+1).stripWhiteSpace().lower();
if (pattern.isEmpty() || encoding.isEmpty())
{
continue;
}
cd = portable_iconv_open("UTF-8",encoding.data());
if (cd==reinterpret_cast<void *>(-1))
{
term("unsupported character conversion: '%s'->'%s': %s\n"
"Check the 'INPUT_FILE_ENCODING' setting in the config file!\n",
qPrint(encoding),qPrint("UTF-8"),strerror(errno));
}
else
{
portable_iconv_close(cd);
}
Doxygen::inputFileEncodingList.push_back(InputFileEncoding(pattern, encoding));
}
}
// add predefined macro name to a dictionary
// 添加预定义的宏定义到字典中
// https://www.doxygen.nl/manual/config.html#cfg_expand_as_defined
const StringVector &expandAsDefinedList =Config_getList(EXPAND_AS_DEFINED);
for (const auto &s : expandAsDefinedList)
{
Doxygen::expandAsDefinedSet.insert(s.c_str());
}
// read aliases and store them in a dictionary
// 读取别名， 并存储到字典中
// https://www.doxygen.nl/manual/config.html#cfg_aliases
readAliases();
// store number of spaces in a tab into Doxygen::spaces
// 读取 tab 制表符的宽度. 默认是4
// https://www.doxygen.nl/manual/config.html#cfg_tab_size
int tabSize = Config_getInt(TAB_SIZE);
Doxygen::spaces.resize(tabSize+1);
int sp;for (sp=0;sp<tabSize;sp++) Doxygen::spaces.at(sp)=' ';
Doxygen::spaces.at(tabSize)='\0';
}
7. parseInput(): 解析输入的过程浅析
函数本体大约600行代码， 考虑到调用的一些函数的代码， 总计超过1000行。过程较复杂，包含的内容很多。
// src/doxygen.cpp, L11727-L12348
void parseInput()
{
AUTO_TRACE();
std::atexit(exitDoxygen); // atexit 是注册整个程序运行结束(main()之后)要执行的函数。如果doxygen运行中出错提前结束，并且 DB 文件(filterDBFileNmae)不为空, 则删除这个文件
// 检查是否配置了使用 clang parser。默认是 False。 如果要开启， 还需要编译 doxygen 时传入 -Duse_libclang=ON
// https://www.doxygen.nl/manual/config.html#cfg_clang_assisted_parsing
#if USE_LIBCLANG
Doxygen::clangAssistedParsing = Config_getBool(CLANG_ASSISTED_PARSING);
#endif
// we would like to show the versionString earlier, but we first have to handle the configuration file
// to know the value of the QUIET setting.
QCString versionString = getFullVersion(); // 获取完整的版本字符串
msg("Doxygen version used: %s\n",qPrint(versionString));
// DOT_PATH 配置项， 给出了 dot 命令所在的目录
// https://www.doxygen.nl/manual/config.html#cfg_DOT_PATH
// computeVerifiedDotPath() 根据给出的 DOT_PATH 的取值作为目录， 拼接得到 dot 命令的路径。如果是 windows 还会添加 .exe 后缀
computeVerifiedDotPath();
/**************************************************************************
* Make sure the output directory exists
**************************************************************************/
// OUTPUT_DIRECTORY: https://www.doxygen.nl/manual/config.html#cfg_output_directory
// 解析用户指定的文档输出路径。支持相对路径。如果留空则用当前目录。
QCString outputDirectory = Config_getString(OUTPUT_DIRECTORY);
if (outputDirectory.isEmpty())
{
outputDirectory = Config_updateString(OUTPUT_DIRECTORY,Dir::currentDirPath().c_str());
}
else
{
Dir dir(outputDirectory.str());
if (!dir.exists())
{
dir.setPath(Dir::currentDirPath());
if (!dir.mkdir(outputDirectory.str()))
{
err("tag OUTPUT_DIRECTORY: Output directory '%s' does not "
"exist and cannot be created\n",qPrint(outputDirectory));
cleanUpDoxygen();
exit(1);
}
else
{
msg("Notice: Output directory '%s' does not exist. "
"I have created it for you.\n", qPrint(outputDirectory));
}
dir.setPath(outputDirectory.str());
}
outputDirectory = Config_updateString(OUTPUT_DIRECTORY,dir.absPath().c_str());
}
AUTO_TRACE_ADD("outputDirectory={}",outputDirectory);
/**************************************************************************
* Initialize global lists and dictionaries
**************************************************************************/
// 初始化全局的列表和字典
// 可以使用lookup_cache_size设置符号查找缓存的大小。此缓存用于解析给定名称和范围的符号。
// also scale lookup cache with SYMBOL_CACHE_SIZE
// https://www.doxygen.nl/manual/config.html#cfg_lookup_cache_size
int cacheSize = Config_getInt(LOOKUP_CACHE_SIZE);
if (cacheSize<0) cacheSize=0;
if (cacheSize>9) cacheSize=9;
uint32_t lookupSize = 65536 << cacheSize;
Doxygen::typeLookupCache = new Cache<std::string,LookupInfo>(lookupSize);
Doxygen::symbolLookupCache = new Cache<std::string,LookupInfo>(lookupSize);
#ifdef HAS_SIGNALS
signal(SIGINT, stopDoxygen);
#endif
// 获取当前进程的 ID, 用于 filterdb 文件的命名
uint32_t pid = Portable::pid();
Doxygen::filterDBFileName.sprintf("doxygen_filterdb_%d.tmp",pid);
Doxygen::filterDBFileName.prepend(outputDirectory+"/");
/**************************************************************************
* Check/create output directories *
**************************************************************************/
// 检查输出目录
QCString htmlOutput;
// GENERATE_HTML: https://www.doxygen.nl/manual/config.html#cfg_generate_html
// 是否输出 html 文件。 默认为 YES。
bool generateHtml = Config_getBool(GENERATE_HTML);
if (generateHtml || g_useOutputTemplate /* TODO: temp hack */)
{
htmlOutput = createOutputDirectory(outputDirectory,Config_getString(HTML_OUTPUT),"/html");
Config_updateString(HTML_OUTPUT,htmlOutput);
// SITEMAP_URL: https://www.doxygen.nl/manual/config.html#cfg_sitemap_url
// html 文档部署时使用的完整 URL
QCString sitemapUrl = Config_getString(SITEMAP_URL);
bool generateSitemap = !sitemapUrl.isEmpty();
if (generateSitemap && !sitemapUrl.endsWith("/"))
{
Config_updateString(SITEMAP_URL,sitemapUrl+"/");
}
// add HTML indexers that are enabled
// GENERATE_HTMLHELP: https://www.doxygen.nl/manual/config.html#cfg_generate_htmlhelp 。默认为 NO。
// 如果为YES，则生成三个额外的文件: index.hhp, index.hhc, and index.hhk
// - index.hhp: 生成 HTML Help Project 文件. 在 Windows 系统上，使用 HTML Help Workshop 工具， 选择 hhp 文件和 html 文件，可以生成 .chm 文件
// .chm 是 compiled HTML file 缩写，是单个文件.
bool generateHtmlHelp = Config_getBool(GENERATE_HTMLHELP);
// GENERATE_ECLIPSEHELP: https://www.doxygen.nl/manual/config.html#cfg_generate_eclipsehelp
// 用于生成 eclipse 里的文档页面
bool generateEclipseHelp = Config_getBool(GENERATE_ECLIPSEHELP);
// GENERATE_QHP: https://www.doxygen.nl/manual/config.html#cfg_generate_qhp
// 用于生成 Qt 里的文档页面
bool generateQhp = Config_getBool(GENERATE_QHP);
// GENERATE_TREEVIEW: https://www.doxygen.nl/manual/config.html#cfg_generate_treeview
// GENERATE_TREEVIEW标记用于指定是否应生成树状索引结构来显示分层信息。
// 如果标记值设置为YES，将生成一个包含树状索引结构的侧面板（就像为HTML帮助生成的一样）。为此，需要一个支持JavaScript、DHTML、CSS和框架的浏览器（即任何现代浏览器）。
//
// 通过自定义样式表（请参阅HTML_EXTRA_STYLESHEET），可以进一步微调索引的外观（请参阅微调输出）。
// 例如，doxygen生成的默认样式表有一个示例，显示了如何将图像放在树的根而不是PROJECT_NAME。
//
// 由于树基本上具有与选项卡索引相同的信息，因此在启用此选项时，可以考虑将DISABLE_index设置为YES。
bool generateTreeView = Config_getBool(GENERATE_TREEVIEW);
// GENERATE_DOCSET: https://www.doxygen.nl/manual/config.html#cfg_generate_docset
// 用于生成 XCode 里的文档
bool generateDocSet = Config_getBool(GENERATE_DOCSET);
if (generateEclipseHelp) Doxygen::indexList->addIndex<EclipseHelp>(); // 如果用 Eclipse， 可以开启这个选项。
if (generateHtmlHelp) Doxygen::indexList->addIndex<HtmlHelp>(); // 如果配置了， 则生成 index.hhp 文件， 如果打算生成 Windows .chm电子书，则开启它。
if (generateQhp) Doxygen::indexList->addIndex<Qhp>(); // 如果配置了， 则生成 qt 的文档支持。 本人不用 Qt， 关闭。
if (generateSitemap) Doxygen::indexList->addIndex<Sitemap>(); // 如果配置了， 则生成 sitemap 的支持。 通常对于 html 输出， 应该开启这个。
if (generateTreeView) Doxygen::indexList->addIndex<FTVHelp>(TRUE); // 如果配置了， 则添加 treeview 的支持。通常对于 html 输出， 应该开启这个。
if (generateDocSet) Doxygen::indexList->addIndex<DocSets>(); // 如果配置了， 则添加 XCode 文档生成的支持
Doxygen::indexList->initialize(); // 对每个 list item， 执行 dispatch_call(). 详见 src/dispatcher.h
}
// GENERATE_DOCBOOK: https://www.doxygen.nl/manual/config.html#cfg_generate_docbook
// 如果为 YES， 则生成 docbook。 docbook 用于生成 pdf。 docbook 基本上还是用xml写的一些文件。
QCString docbookOutput;
bool generateDocbook = Config_getBool(GENERATE_DOCBOOK);
if (generateDocbook)
{
docbookOutput = createOutputDirectory(outputDirectory,Config_getString(DOCBOOK_OUTPUT),"/docbook");
Config_updateString(DOCBOOK_OUTPUT,docbookOutput);
}
// GENERATE_XML: https://www.doxygen.nl/manual/config.html#cfg_generate_xml
// If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that captures the structure of the code including all documentation.
// 不是很熟悉 xml 输出， 看起来 xml 输出更多的是作为结构化结果， 是一种中间表示（IR），而不是最终给用户看的
QCString xmlOutput;
bool generateXml = Config_getBool(GENERATE_XML);
if (generateXml)
{
xmlOutput = createOutputDirectory(outputDirectory,Config_getString(XML_OUTPUT),"/xml");
Config_updateString(XML_OUTPUT,xmlOutput);
}
// 生成 latex。
QCString latexOutput;
bool generateLatex = Config_getBool(GENERATE_LATEX);
if (generateLatex)
{
latexOutput = createOutputDirectory(outputDirectory,Config_getString(LATEX_OUTPUT), "/latex");
Config_updateString(LATEX_OUTPUT,latexOutput);
}
// 生成 rtf
QCString rtfOutput;
bool generateRtf = Config_getBool(GENERATE_RTF);
if (generateRtf)
{
rtfOutput = createOutputDirectory(outputDirectory,Config_getString(RTF_OUTPUT),"/rtf");
Config_updateString(RTF_OUTPUT,rtfOutput);
}
// 生成 man 页面
QCString manOutput;
bool generateMan = Config_getBool(GENERATE_MAN);
if (generateMan)
{
manOutput = createOutputDirectory(outputDirectory,Config_getString(MAN_OUTPUT),"/man");
Config_updateString(MAN_OUTPUT,manOutput);
}
// 生成 sqlite3 输出
#if USE_SQLITE3
QCString sqlOutput;
bool generateSql = Config_getBool(GENERATE_SQLITE3);
if (generateSql)
{
sqlOutput = createOutputDirectory(outputDirectory,Config_getString(SQLITE3_OUTPUT),"/sqlite3");
Config_updateString(SQLITE3_OUTPUT,sqlOutput);
}
#endif
// 如果安装了 dot 命令， 并且 DOT_FONTPATH 配置项为 YES， 则配置 dot 使用的字体
if (Config_getBool(HAVE_DOT))
{
QCString curFontPath = Config_getString(DOT_FONTPATH);
if (curFontPath.isEmpty())
{
Portable::getenv("DOTFONTPATH");
QCString newFontPath = ".";
if (!curFontPath.isEmpty())
{
newFontPath+=Portable::pathListSeparator();
newFontPath+=curFontPath;
}
Portable::setenv("DOTFONTPATH",qPrint(newFontPath));
}
else
{
Portable::setenv("DOTFONTPATH",qPrint(curFontPath));
}
}
/**************************************************************************
* Handle layout file *
**************************************************************************/
// 处理布局文件. 默认布局文件是 DoxygenLayout.xml
LayoutDocManager::instance().init();
QCString layoutFileName = Config_getString(LAYOUT_FILE);
bool defaultLayoutUsed = FALSE;
if (layoutFileName.isEmpty())
{
layoutFileName = Config_updateString(LAYOUT_FILE,"DoxygenLayout.xml");
defaultLayoutUsed = TRUE;
}
AUTO_TRACE_ADD("defaultLayoutUsed={}, layoutFileName={}",defaultLayoutUsed,layoutFileName);
FileInfo fi(layoutFileName.str());
if (fi.exists())
{
msg("Parsing layout file %s...\n",qPrint(layoutFileName));
LayoutDocManager::instance().parse(layoutFileName);
}
else if (!defaultLayoutUsed)
{
warn_uncond("failed to open layout file '%s' for reading! Using default settings.\n",qPrint(layoutFileName));
}
/**************************************************************************
* Read and preprocess input *
**************************************************************************/
// prevent search in the output directories
// 对于每一种输出类型（html，latex等）， 不要作为生成文档的输入。
// EXCLUDE_PATTERNS: https://www.doxygen.nl/manual/config.html#cfg_exclude_patterns
StringVector exclPatterns = Config_getList(EXCLUDE_PATTERNS);
if (generateHtml) exclPatterns.push_back(htmlOutput.str());
if (generateDocbook) exclPatterns.push_back(docbookOutput.str());
if (generateXml) exclPatterns.push_back(xmlOutput.str());
if (generateLatex) exclPatterns.push_back(latexOutput.str());
if (generateRtf) exclPatterns.push_back(rtfOutput.str());
if (generateMan) exclPatterns.push_back(manOutput.str());
Config_updateList(EXCLUDE_PATTERNS,exclPatterns);
// 搜索输入文件。 包括这几种类型：
// INCLUDE_PATH: 包含的文件
// EXAMPLE_PATH: 文件名字或目录， 存储例子代码。 用于使用 `\include` 命令时将一个文件的内容作为一个block引入
// IMAGE_PATH: 图像路径。
// DOTFILE_DIRS：类似前面几个。
// MSCFILE_DIRS
// DIAFILE_DIRS
// EXCLUDE
searchInputFiles();
// 检查 markdown 主文件， 用于作为 html 页面的主页
checkMarkdownMainfile();
// Notice: the order of the function calls below is very important!
// 如下几个判断的顺序不能修改
if (Config_getBool(GENERATE_HTML) && !Config_getBool(USE_MATHJAX))
{
FormulaManager::instance().initFromRepository(Config_getString(HTML_OUTPUT));
}
if (Config_getBool(GENERATE_RTF))
{
FormulaManager::instance().initFromRepository(Config_getString(RTF_OUTPUT));
}
if (Config_getBool(GENERATE_DOCBOOK))
{
FormulaManager::instance().initFromRepository(Config_getString(DOCBOOK_OUTPUT));
}
FormulaManager::instance().checkRepositories();
/**************************************************************************
* Handle Tag Files *
**************************************************************************/
// 处理 tag 文件
std::shared_ptr<Entry> root = std::make_shared<Entry>();
msg("Reading and parsing tag files\n");
const StringVector &tagFileList = Config_getList(TAGFILES);
for (const auto &s : tagFileList)
{
readTagFile(root,s.c_str());
}
/**************************************************************************
* Parse source files *
**************************************************************************/
// 处理源代码文件
// 增加 STL 支持
addSTLSupport(root);
g_s.begin("Parsing files\n");
// doxygen 解析文件时， 默认单线程， 也可以指定多线程的数量, 最大32
// https://www.doxygen.nl/manual/config.html#cfg_num_proc_threads
if (Config_getInt(NUM_PROC_THREADS)==1)
{
parseFilesSingleThreading(root);
}
else
{
parseFilesMultiThreading(root);
}
g_s.end();
/**************************************************************************
* Gather information *
**************************************************************************/
// 收集信息. g_s 是 Statistics 类的实例。
g_s.begin("Building macro definition list...\n");
// 宏定义: 把预处理阶段扫描出的宏定义， 作为文件成员
buildDefineList();
g_s.end();
g_s.begin("Building group list...\n");
// group 的处理。也就是被提取文档的 C/C++ 代码中的 @defgroups, @addtogroup, @weakgroup 区块中的group
buildGroupList(root.get());
organizeSubGroups(root.get());
g_s.end();
g_s.begin("Building directory list...\n");
// 目录的处理
buildDirectories();
findDirDocumentation(root.get());
g_s.end();
g_s.begin("Building namespace list...\n");
// 命名空间的处理
buildNamespaceList(root.get());
findUsingDirectives(root.get());
g_s.end();
g_s.begin("Building file list...\n");
// 文件的处理
buildFileList(root.get());
g_s.end();
g_s.begin("Building class list...\n");
// 类的处理
buildClassList(root.get());
g_s.end();
g_s.begin("Building concept list...\n");
// C++ concept 的处理
buildConceptList(root.get());
g_s.end();
// build list of using declarations here (global list)
// C++ using 的处理，例如 using cout=std::cout
buildListOfUsingDecls(root.get());
g_s.end();
g_s.begin("Computing nesting relations for classes...\n");
// 解决 C++ 类的嵌套关系
resolveClassNestingRelations();
g_s.end();
// 1.8.2-20121111: no longer add nested classes to the group as well
//distributeClassGroupRelations();
// calling buildClassList may result in cached relations that
// become invalid after resolveClassNestingRelations(), that's why
// we need to clear the cache here
Doxygen::typeLookupCache->clear();
// we don't need the list of using declaration anymore
g_usingDeclarations.clear();
g_s.begin("Associating documentation with classes...\n");
// 构建类文档列表
buildClassDocList(root.get());
g_s.end();
g_s.begin("Associating documentation with concepts...\n");
// 构建concept的文档列表
buildConceptDocList(root.get());
distributeConceptGroups();
g_s.end();
g_s.begin("Building example list...\n");
// 构建 examples 列表
buildExampleList(root.get());
g_s.end();
g_s.begin("Searching for enumerations...\n");
// 查找枚举类型
findEnums(root.get());
g_s.end();
// Since buildVarList calls isVarWithConstructor
// and this calls getResolvedClass we need to process
// typedefs first so the relations between classes via typedefs
// are properly resolved. See bug 536385 for an example.
g_s.begin("Searching for documented typedefs...\n");
// 处理 typedef
buildTypedefList(root.get());
g_s.end();
if (Config_getBool(OPTIMIZE_OUTPUT_SLICE))
{
g_s.begin("Searching for documented sequences...\n");
buildSequenceList(root.get());
g_s.end();
g_s.begin("Searching for documented dictionaries...\n");
buildDictionaryList(root.get());
g_s.end();
}
g_s.begin("Searching for members imported via using declarations...\n");
// this should be after buildTypedefList in order to properly import
// used typedefs
findUsingDeclarations(root.get(),TRUE); // do for python packages first
findUsingDeclarations(root.get(),FALSE); // then the rest
g_s.end();
g_s.begin("Searching for included using directives...\n");
findIncludedUsingDirectives();
g_s.end();
g_s.begin("Searching for documented variables...\n");
// 处理变量
buildVarList(root.get());
g_s.end();
g_s.begin("Building interface member list...\n");
buildInterfaceAndServiceList(root.get()); // UNO IDL
g_s.begin("Building member list...\n"); // using class info only !
// 处理函数
buildFunctionList(root.get());
g_s.end();
g_s.begin("Searching for friends...\n");
// 处理 C++ 友元
findFriends();
g_s.end();
g_s.begin("Searching for documented defines...\n");
findDefineDocumentation(root.get());
g_s.end();
g_s.begin("Computing class inheritance relations...\n");
findClassEntries(root.get());
findInheritedTemplateInstances();
g_s.end();
g_s.begin("Computing class usage relations...\n");
// 计算类之间的关系
findUsedTemplateInstances();
g_s.end();
if (Config_getBool(INLINE_SIMPLE_STRUCTS))
{
g_s.begin("Searching for tag less structs...\n");
findTagLessClasses();
g_s.end();
}
g_s.begin("Flushing cached template relations that have become invalid...\n");
flushCachedTemplateRelations();
g_s.end();
g_s.begin("Computing class relations...\n");
computeTemplateClassRelations();
flushUnresolvedRelations();
if (Config_getBool(OPTIMIZE_OUTPUT_VHDL))
{
VhdlDocGen::computeVhdlComponentRelations();
}
computeClassRelations();
g_classEntries.clear();
g_s.end();
g_s.begin("Add enum values to enums...\n");
addEnumValuesToEnums(root.get());
findEnumDocumentation(root.get());
g_s.end();
g_s.begin("Searching for member function documentation...\n");
findObjCMethodDefinitions(root.get());
findMemberDocumentation(root.get()); // may introduce new members !
findUsingDeclImports(root.get()); // may introduce new members !
transferRelatedFunctionDocumentation();
transferFunctionDocumentation();
g_s.end();
// moved to after finding and copying documentation,
// as this introduces new members see bug 722654
g_s.begin("Creating members for template instances...\n");
// 处理模板实例的成员
createTemplateInstanceMembers();
g_s.end();
g_s.begin("Building page list...\n");
// 处理页面
buildPageList(root.get());
g_s.end();
g_s.begin("Search for main page...\n");
// 文档主页
findMainPage(root.get());
findMainPageTagFiles(root.get());
g_s.end();
g_s.begin("Computing page relations...\n");
computePageRelations(root.get());
checkPageRelations();
g_s.end();
g_s.begin("Determining the scope of groups...\n");
findGroupScope(root.get());
g_s.end();
// 成员名字比较函数， 用于排序
auto memberNameComp = [](const MemberNameLinkedMap::Ptr &n1,const MemberNameLinkedMap::Ptr &n2)
{
return qstricmp(n1->memberName().data()+getPrefixIndex(n1->memberName()),
n2->memberName().data()+getPrefixIndex(n2->memberName())
)<0;
};
// 类比较函数， 用于排序
auto classComp = [](const ClassLinkedMap::Ptr &c1,const ClassLinkedMap::Ptr &c2)
{
if (Config_getBool(SORT_BY_SCOPE_NAME))
{
return qstricmp(c1->name(), c2->name())<0;
}
else
{
int i = qstricmp(c1->className(), c2->className());
return i==0 ? qstricmp(c1->name(), c2->name())<0 : i<0;
}
};
// 命名空间比较函数，用于排序
auto namespaceComp = [](const NamespaceLinkedMap::Ptr &n1,const NamespaceLinkedMap::Ptr &n2)
{
return qstricmp(n1->name(),n2->name())<0;
};
// concept 比较函数， 用于排序
auto conceptComp = [](const ConceptLinkedMap::Ptr &c1,const ConceptLinkedMap::Ptr &c2)
{
return qstricmp(c1->name(),c2->name())<0;
};
// 排序列表
g_s.begin("Sorting lists...\n");
std::sort(Doxygen::memberNameLinkedMap->begin(),
Doxygen::memberNameLinkedMap->end(),
memberNameComp);
std::sort(Doxygen::functionNameLinkedMap->begin(),
Doxygen::functionNameLinkedMap->end(),
memberNameComp);
std::sort(Doxygen::hiddenClassLinkedMap->begin(),
Doxygen::hiddenClassLinkedMap->end(),
classComp);
std::sort(Doxygen::classLinkedMap->begin(),
Doxygen::classLinkedMap->end(),
classComp);
std::sort(Doxygen::conceptLinkedMap->begin(),
Doxygen::conceptLinkedMap->end(),
conceptComp);
std::sort(Doxygen::namespaceLinkedMap->begin(),
Doxygen::namespaceLinkedMap->end(),
namespaceComp);
g_s.end();
g_s.begin("Determining which enums are documented\n");
// 寻找被文档标注的枚举值
findDocumentedEnumValues();
g_s.end();
g_s.begin("Computing member relations...\n");
// 合并类别
mergeCategories();
// 计算成员关系
computeMemberRelations();
g_s.end();
g_s.begin("Building full member lists recursively...\n");
buildCompleteMemberLists();
g_s.end();
g_s.begin("Adding members to member groups.\n");
addMembersToMemberGroup();
g_s.end();
if (Config_getBool(DISTRIBUTE_GROUP_DOC))
{
g_s.begin("Distributing member group documentation.\n");
distributeMemberGroupDocumentation();
g_s.end();
}
g_s.begin("Computing member references...\n");
computeMemberReferences();
g_s.end();
if (Config_getBool(INHERIT_DOCS))
{
g_s.begin("Inheriting documentation...\n");
inheritDocumentation();
g_s.end();
}
// compute the shortest possible names of all files
// without losing the uniqueness of the file names.
g_s.begin("Generating disk names...\n");
generateDiskNames();
g_s.end();
g_s.begin("Adding source references...\n");
addSourceReferences();
g_s.end();
g_s.begin("Adding xrefitems...\n");
addListReferences();
generateXRefPages();
g_s.end();
g_s.begin("Sorting member lists...\n");
sortMemberLists();
g_s.end();
g_s.begin("Setting anonymous enum type...\n");
setAnonymousEnumType();
g_s.end();
if (Config_getBool(DIRECTORY_GRAPH))
{
g_s.begin("Computing dependencies between directories...\n");
computeDirDependencies();
g_s.end();
}
g_s.begin("Generating citations page...\n");
CitationManager::instance().generatePage();
g_s.end();
g_s.begin("Counting members...\n");
countMembers();
g_s.end();
g_s.begin("Counting data structures...\n");
Index::instance().countDataStructures();
g_s.end();
g_s.begin("Resolving user defined references...\n");
resolveUserReferences();
g_s.end();
g_s.begin("Finding anchors and sections in the documentation...\n");
findSectionsInDocumentation();
g_s.end();
g_s.begin("Transferring function references...\n");
transferFunctionReferences();
g_s.end();
g_s.begin("Combining using relations...\n");
combineUsingRelations();
g_s.end();
initSearchIndexer();
g_s.begin("Adding members to index pages...\n");
addMembersToIndex();
addToIndices();
g_s.end();
g_s.begin("Correcting members for VHDL...\n");
vhdlCorrectMemberProperties();
g_s.end();
g_s.begin("Computing tooltip texts...\n");
computeTooltipTexts();
g_s.end();
if (Config_getBool(SORT_GROUP_NAMES))
{
std::sort(Doxygen::groupLinkedMap->begin(),
Doxygen::groupLinkedMap->end(),
[](const auto &g1,const auto &g2)
{ return g1->groupTitle() < g2->groupTitle(); });
for (const auto &gd : *Doxygen::groupLinkedMap)
{
gd->sortSubGroups();
}
}
}
8. generateOutput(): 生成输出的过程浅析
- dump 所有的符号表
- 生成 html
- 生成 latex
- 生成 man
- 生成 docbook
- 生成 RTF
- 生成 HTAGS
这里主要关注 html， 其他格式忽略。 html 相关的具体生成， 涉及如下功能/函数调用:
- 生成图片 generateImages()
- 生成例子文档 generateExampleDocs()
- 生成文件源代码 generateFileSources()
- 生成文件列表 generateFileDocs()
- 生成page页面 generatePageDocs()
- 生成group页面 generateGroupDocs()
- 生成class页面 generateClassDocs()
- 生成concept页面 generateConceptDocs()
- 生成命名空间页面 generateNamespaceDocs()
- 生成目录页面 generateDirDocs()
- 生成 tag 文件 writeTagFile()
- 生成 html 搜索页面 writeSearchPage()
- 生成 .chm 电子书 runHtmlHelpCompiler()
- 输出统计信息（文档生成耗时）
代码过多， 这一小节没有具体的注释， 但后续值得具体分析和调试。
// src/doxygen.cpp L12350-L12718
void generateOutput()
{
AUTO_TRACE();
/**************************************************************************
* Initialize output generators *
**************************************************************************/
/// add extra languages for which we can only produce syntax highlighted code
addCodeOnlyMappings();
dump all symbols
if (g_dumpSymbolMap)
{
dumpSymbolMap();
exit(0);
}
bool generateHtml = Config_getBool(GENERATE_HTML);
bool generateLatex = Config_getBool(GENERATE_LATEX);
bool generateMan = Config_getBool(GENERATE_MAN);
bool generateRtf = Config_getBool(GENERATE_RTF);
bool generateDocbook = Config_getBool(GENERATE_DOCBOOK);
g_outputList = new OutputList;
if (generateHtml)
{
g_outputList->add<HtmlGenerator>();
HtmlGenerator::init();
HtmlGenerator::writeTabData();
}
if (generateLatex)
{
g_outputList->add<LatexGenerator>();
LatexGenerator::init();
}
if (generateDocbook)
{
g_outputList->add<DocbookGenerator>();
DocbookGenerator::init();
}
if (generateMan)
{
g_outputList->add<ManGenerator>();
ManGenerator::init();
}
if (generateRtf)
{
g_outputList->add<RTFGenerator>();
RTFGenerator::init();
}
if (Config_getBool(USE_HTAGS))
{
Htags::useHtags = TRUE;
QCString htmldir = Config_getString(HTML_OUTPUT);
if (!Htags::execute(htmldir))
err("USE_HTAGS is YES but htags(1) failed. \n");
else if (!Htags::loadFilemap(htmldir))
err("htags(1) ended normally but failed to load the filemap. \n");
}
/**************************************************************************
* Generate documentation *
**************************************************************************/
g_s.begin("Generating style sheet...\n");
//printf("writing style info\n");
g_outputList->writeStyleInfo(0); // write first part
g_s.end();
bool searchEngine = Config_getBool(SEARCHENGINE);
bool serverBasedSearch = Config_getBool(SERVER_BASED_SEARCH);
g_s.begin("Generating search indices...\n");
if (searchEngine && !serverBasedSearch && (generateHtml || g_useOutputTemplate))
{
createJavaScriptSearchIndex();
}
// generate search indices (need to do this before writing other HTML
// pages as these contain a drop down menu with options depending on
// what categories we find in this function.
if (generateHtml && searchEngine)
{
QCString searchDirName = Config_getString(HTML_OUTPUT)+"/search";
Dir searchDir(searchDirName.str());
if (!searchDir.exists() && !searchDir.mkdir(searchDirName.str()))
{
term("Could not create search results directory '%s' $PWD='%s'\n",
qPrint(searchDirName),Dir::currentDirPath().c_str());
}
HtmlGenerator::writeSearchData(searchDirName);
if (!serverBasedSearch) // client side search index
{
writeJavaScriptSearchIndex();
}
}
g_s.end();
// copy static stuff
if (generateHtml)
{
FTVHelp::generateTreeViewImages();
copyStyleSheet();
copyLogo(Config_getString(HTML_OUTPUT));
copyExtraFiles(Config_getList(HTML_EXTRA_FILES),"HTML_EXTRA_FILES",Config_getString(HTML_OUTPUT));
}
if (generateLatex)
{
copyLatexStyleSheet();
copyLogo(Config_getString(LATEX_OUTPUT));
copyExtraFiles(Config_getList(LATEX_EXTRA_FILES),"LATEX_EXTRA_FILES",Config_getString(LATEX_OUTPUT));
}
if (generateDocbook)
{
copyLogo(Config_getString(DOCBOOK_OUTPUT));
}
if (generateRtf)
{
copyLogo(Config_getString(RTF_OUTPUT));
}
FormulaManager &fm = FormulaManager::instance();
if (fm.hasFormulas() && generateHtml
&& !Config_getBool(USE_MATHJAX))
{
g_s.begin("Generating images for formulas in HTML...\n");
fm.generateImages(Config_getString(HTML_OUTPUT), Config_getEnum(HTML_FORMULA_FORMAT)==HTML_FORMULA_FORMAT_t::svg ?
FormulaManager::Format::Vector : FormulaManager::Format::Bitmap, FormulaManager::HighDPI::On);
g_s.end();
}
if (fm.hasFormulas() && generateRtf)
{
g_s.begin("Generating images for formulas in RTF...\n");
fm.generateImages(Config_getString(RTF_OUTPUT),FormulaManager::Format::Bitmap);
g_s.end();
}
if (fm.hasFormulas() && generateDocbook)
{
g_s.begin("Generating images for formulas in Docbook...\n");
fm.generateImages(Config_getString(DOCBOOK_OUTPUT),FormulaManager::Format::Bitmap);
g_s.end();
}
g_s.begin("Generating example documentation...\n");
generateExampleDocs();
g_s.end();
warn_flush();
g_s.begin("Generating file sources...\n");
generateFileSources();
g_s.end();
g_s.begin("Generating file documentation...\n");
generateFileDocs();
g_s.end();
g_s.begin("Generating page documentation...\n");
generatePageDocs();
g_s.end();
g_s.begin("Generating group documentation...\n");
generateGroupDocs();
g_s.end();
g_s.begin("Generating class documentation...\n");
generateClassDocs();
g_s.end();
g_s.begin("Generating concept documentation...\n");
generateConceptDocs();
g_s.end();
g_s.begin("Generating namespace documentation...\n");
generateNamespaceDocs();
g_s.end();
if (Config_getBool(GENERATE_LEGEND))
{
g_s.begin("Generating graph info page...\n");
writeGraphInfo(*g_outputList);
g_s.end();
}
g_s.begin("Generating directory documentation...\n");
generateDirDocs(*g_outputList);
g_s.end();
if (g_outputList->size()>0)
{
writeIndexHierarchy(*g_outputList);
}
g_s.begin("finalizing index lists...\n");
Doxygen::indexList->finalize();
g_s.end();
g_s.begin("writing tag file...\n");
writeTagFile();
g_s.end();
if (Config_getBool(GENERATE_XML))
{
g_s.begin("Generating XML output...\n");
Doxygen::generatingXmlOutput=TRUE;
generateXML();
Doxygen::generatingXmlOutput=FALSE;
g_s.end();
}
#if USE_SQLITE3
if (Config_getBool(GENERATE_SQLITE3))
{
g_s.begin("Generating SQLITE3 output...\n");
generateSqlite3();
g_s.end();
}
#endif
if (Config_getBool(GENERATE_AUTOGEN_DEF))
{
g_s.begin("Generating AutoGen DEF output...\n");
generateDEF();
g_s.end();
}
if (Config_getBool(GENERATE_PERLMOD))
{
g_s.begin("Generating Perl module output...\n");
generatePerlMod();
g_s.end();
}
if (generateHtml && searchEngine && serverBasedSearch)
{
g_s.begin("Generating search index\n");
if (Doxygen::searchIndex->kind()==SearchIndexIntf::Internal) // write own search index
{
HtmlGenerator::writeSearchPage();
Doxygen::searchIndex->write(Config_getString(HTML_OUTPUT)+"/search/search.idx");
}
else // write data for external search index
{
HtmlGenerator::writeExternalSearchPage();
QCString searchDataFile = Config_getString(SEARCHDATA_FILE);
if (searchDataFile.isEmpty())
{
searchDataFile="searchdata.xml";
}
if (!Portable::isAbsolutePath(searchDataFile.data()))
{
searchDataFile.prepend(Config_getString(OUTPUT_DIRECTORY)+"/");
}
Doxygen::searchIndex->write(searchDataFile);
}
g_s.end();
}
if (g_useOutputTemplate)
{
g_s.begin("Generating output via template engine...\n");
generateOutputViaTemplate();
g_s.end();
}
warn_flush();
if (generateRtf)
{
g_s.begin("Combining RTF output...\n");
if (!RTFGenerator::preProcessFileInplace(Config_getString(RTF_OUTPUT),"refman.rtf"))
{
err("An error occurred during post-processing the RTF files!\n");
}
g_s.end();
}
warn_flush();
g_s.begin("Running plantuml with JAVA...\n");
PlantumlManager::instance().run();
g_s.end();
warn_flush();
if (Config_getBool(HAVE_DOT))
{
g_s.begin("Running dot...\n");
DotManager::instance()->run();
g_s.end();
}
if (generateHtml &&
Config_getBool(GENERATE_HTMLHELP) &&
!Config_getString(HHC_LOCATION).isEmpty())
{
g_s.begin("Running html help compiler...\n");
runHtmlHelpCompiler();
g_s.end();
}
warn_flush();
if ( generateHtml &&
Config_getBool(GENERATE_QHP) &&
!Config_getString(QHG_LOCATION).isEmpty())
{
g_s.begin("Running qhelpgenerator...\n");
runQHelpGenerator();
g_s.end();
}
g_outputList->cleanup();
msg("type lookup cache used %zu/%zu hits=%" PRIu64 " misses=%" PRIu64 "\n",
Doxygen::typeLookupCache->size(),
Doxygen::typeLookupCache->capacity(),
Doxygen::typeLookupCache->hits(),
Doxygen::typeLookupCache->misses());
msg("symbol lookup cache used %zu/%zu hits=%" PRIu64 " misses=%" PRIu64 "\n",
Doxygen::symbolLookupCache->size(),
Doxygen::symbolLookupCache->capacity(),
Doxygen::symbolLookupCache->hits(),
Doxygen::symbolLookupCache->misses());
int typeCacheParam = computeIdealCacheParam(static_cast<size_t>(Doxygen::typeLookupCache->misses()*2/3)); // part of the cache is flushed, hence the 2/3 correction factor
int symbolCacheParam = computeIdealCacheParam(static_cast<size_t>(Doxygen::symbolLookupCache->misses()));
int cacheParam = std::max(typeCacheParam,symbolCacheParam);
if (cacheParam>Config_getInt(LOOKUP_CACHE_SIZE))
{
msg("Note: based on cache misses the ideal setting for LOOKUP_CACHE_SIZE is %d at the cost of higher memory usage.\n",cacheParam);
}
if (Debug::isFlagSet(Debug::Time))
{
std::size_t numThreads = static_cast<std::size_t>(Config_getInt(NUM_PROC_THREADS));
if (numThreads<1) numThreads=1;
msg("Total elapsed time: %.6f seconds\n(of which an average of %.6f seconds per thread waiting for external tools to finish)\n",
(static_cast<double>(Debug::elapsedTime())),
Portable::getSysElapsedTime()/static_cast<double>(numThreads)
);
g_s.print();
Debug::clearFlag(Debug::Time);
msg("finished...\n");
Debug::setFlag(Debug::Time);
}
else
{
msg("finished...\n");
}
/**************************************************************************
* Start cleaning up *
**************************************************************************/
cleanUpDoxygen();
finalizeSearchIndexer();
Dir thisDir;
thisDir.remove(Doxygen::filterDBFileName.str());
finishWarnExit();
exitTracing();
Config::deinit();
delete Doxygen::clangUsrMap;
g_successfulRun=TRUE;
//dumpDocNodeSizes();
}
786
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
