关于 DTK 和其它 DDE C++ 组件的文档生成和提供方案讨论

[BLumia]

目前 DTK 和其它 DDE 相关的 C++ 库的文档情况其实并不理想（甚至有点糟糕），于是希望能提供一些方案来解决这个问题。当下的问题大概有这些：

• 文档不全（这个可以让相关项目组的研发来主动补充）
• 公开的文档不够新，已有的在线文档也不能对应到自己实际在使用的版本
• 优先提供的文档是中文文档（英文文档和其它语言文档大概只能靠社区一起来进行翻译）
• 应当尽可能保证代码中不存在非 ascii 字符（也就是要避免代码出现中文，包括文档部分）
• 现有的 C++ 文档工具的多语言翻译支持并不好（doxygen 是写 \~languageId 标记语言的，如果 inline 把文档写代码里，会导致代码异常臃肿，并且研发本身并不能维护其它语言的文档更新）

于是我们打算制定一个文档相关的规范来解决这些问题，在规范里会涵盖这些内容：

• 可实施的文档覆盖率检查（确保新增代码的文档是全的）
• 确保各个语言的文档和代码分离
• 确保文档可以自动生成和发布

---

对于这些要点，目前的解决方案是这样的：

• 与源码分开，单独准备 doc 目录来提供文档。使用 classname.zh_CN.dox 的方式提供 API 文档。
• 使用 @class @fn 声明文档所对应的 API
• 使用 coverxygen 进行覆盖率检查
• 固定使用 CMake 管理文档生成步骤，暴露指定的几个 doxygen 相关的 variable 以供 CI 使用
• 生成 -doc 文档包，提供可在 QtCreator 中直接查看的帮助文档
• 打 tag 时更新网页 HTML 文档

例子项目（只有一个类，仅供测试）： dtkcore.zip

目前的解决方案应该可以解决上述问题，但也存在一些可实施方面的问题，例如对于已有项目，让项目组自己手动创建一大堆 .dox 文件肯定不合适，折中的方案是写个额外的工具来解析 doxygen 的 XML 输出来生成这些文件。

在实际推行这套方案之前，在此先把目前的方案公示出来，看看有没有改进的地方或者更合适的方案，如果有任何想法，希望各位可以参与进来一起讨论下~

[BLumia]

linuxdeepin/dtkcore#71

遵循上述方案的一个相关 CMake 配置已合入，可以直接用此项目测试（此项目暂时还没按照分离 .dox 文件的形式进行文档注释）