Doxygen 中文文档

发布网友 发布时间:2024-12-21 13:41

我来回答

1个回答

热心网友 时间:2025-01-01 06:18

原文:doxygen.nl/manual


本文档将重点介绍Doxygen的使用方法和中文文档相关知识。


Getting started

Doxygen是用于解析源文件并生成文档的主要程序。详细使用方法请参阅Doxygen使用文档。带有界面的程序doxywizard可以用于编辑配置文件和运行Doxygen。主要关系图如下:


Step 0:确认需求

默认支持的语言包括:C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Fortran 和 D。


Step 1:创建配置文件

可以使用命令`doxygen -g`基于模板生成配置文件,其格式类似于Makefile。尝试使用doxywizard编辑配置文件。对于小工程,`INPUT`标签留空,从当前目录查找源文件。对于大型工程,指定具体目录给`INPUT`,通过`FILE_PATTERNS`(如,`.cpp .h`)进行文件匹配,并设置`RECURSIVE`为yes。使用`EXCLUDE`和`EXCLUDE_PATTERNS`进行微调。文件名后缀与对应语言的关系见:doxygen.nl/manual/start...


Step 2:运行doxygen

执行`doxygen`命令。


Step 3:源代码文档化格式

默认`EXTRACT_ALL`值为NO,仅为可识别实体生成文档信息。通过两种方式为namespace、class和成员文档化:第一种常见于代码,第二种适用于其他文档。解析过程如下:


doxygen-代码文档化

详细参见:doxygen.nl/manual/docbl...


怎样写注释源代码中的文档注释

针对C语言,其他语言请查阅原文。每个实体有简短描述和详细描述,方法或函数还包含in-body描述,由主体中所有注释块串联而成。通常一个注释块内只允许一个详细描述和一个简短描述,顺序未定义。(更多示例见原文)


其他位置的文档注释

添加在定义前,对于namespace等,可将文档注释添加到约定位置,方便查找。使用结构化命令(如`\`或`@`开头),如`@class Test`。更多信息见:Special Commands。


美化注释块

可以使用纯文本、markdown格式或部分HTML。支持markdown、markdown extra、XML命令和HTML子集。更多内容参见原文:doxygen.nl/manual/markd...


输出格式

输出格式请参见官网文档:doxygen.nl/manual/output...


查找
客户端查找

使用内置客户端搜索引擎,设置`SEARCHENGINE`和`SERVER_BASED_SEARCH`为yes。支持实时提示,但仅检索符号,不支持全文检索。性能可能受大型项目影响。


服务端查找

将html文档部署到web服务器,使用doxygen内建服务端引擎,设置`SEARCHENGINE`、`SERVER_BASED_SEARCH`为yes,`EXTERNAL_SEARCH`为no。支持全文检索,友好的中等项目支持。不支持本地化检索和实时检索提示。


带外部index的服务端查找

从1.8.3版本开始,提供外部索引和搜索功能。生成可搜索原始数据,供外部工具索引和搜索。使用示例索引器(doxyindexer)和搜索引擎(doxysearch.cgi)。


定制化输出结果
细微调整

调整颜色、布局和XML形式完全控制。可更改色调、饱和度和gamma校正。使用Doxywizard实时预览效果。导航栏可设置为边栏,提供两种导航方式。禁用所有索引。


动态内容

通过页眉、页脚和样式表更改内容。执行命令生成样式表文件,自定义页眉页脚。


改变页面布局

使用layout文件自定义页面布局。默认文件名为DoxygenLayout.xml。定义导航tab、页面元素和自定义tabs。使用xml结构进行编辑。


使用xml定制化输出

详细定制输出结果,请参阅原文:doxygen.nl/manual/custom...


自定义命令

提供特殊命令、XML命令和HTML命令,用于提高注释结构化。如需更多定义,可使用自定义命令。更多信息请查阅原文:doxygen.nl/manual/custom...


常见问题
获取索引页上的信息

使用`\mainpage`标记。


类/文件/命名空间中的部分内容未被文档化

检查配置、文件路径和包含关系。确保所有成员正确注释。


全局函数未被文档化

记录全局函数、变量、枚举、typedef和定义时使用包含`@file`命令的注释块。


自定义扩展名文件无法正确解析

通过`FILE_PATTERNS`匹配特定后缀,并排除不期望的文件。


忽略代码片段

使用`\cond`和`\endcond`标记或通过预处理器实现。


更改类文档中`#include`之后的内容

使用`STRIP_FROM_INC_PATH`或在类注释中指定路径。


排除所有`test`目录

使用`EXCLUDE_PATTERNS`设置路径排除。


STL类依赖未在dot图中显示

启用`BUILTIN_STL_SUPPORT`设置。

声明:本网页内容为用户发布,旨在传播知识,不代表本网认同其观点,若有侵权等问题请及时与本网联系,我们将在第一时间删除处理。
E-MAIL:11247931@qq.com

热门图文