doxygen 5分钟
请用5分钟阅读本文,然后立即投入实践,养成良好的文档习惯,你将节约无数宝贵的屎山打滚时间。
先澄清几个误区:
doxygen 不是写文档的:文档还是要自己写,doxygen 是抽取文档并展示、索引的工具
我的屎山项目没文档,doxygen 对我没用:现在是你最需要doxygen 的时候,它可以通过代码解析生成一份超出你预期的基础文档
doxygen 会改变我的工作习惯:doxygen 可以和你的git push 动作绑定, 自动完成工作。最多你按照规范格式写注释,这事儿有利无害。
doxygen 功能非常多,我只介绍10%最常用的。假设你有一个C++ 工程(doxygen 支持多数主流语言),希望对工程内 src 文件夹内所有头文件和cpp文件生成文档。
初始化配置文件
先进入src 目录,这不是必要的,但这是最自然的。
运行:doxygen -g cpp-template, 生成一个叫 cpp-template 的配置文件。
修改配置文件
按照上一步提示,修改 cpp-template 文件,根据自己的需求订制输出文档的格式、内容。下面是几个主要的配置:
以上内容不言自明,挑出来是因为配置参数太多(260+),这些是我修改过的。
optimize_output_for_c : 强化对c 、c++ 语言的解析
optimize_output_for_java: 强化对java、python 等语言解析,比如包和路径的对应
call_graph, caller_graph: 静态分析函数调用关系, 并生成图形
dot_path: 图形绘制引擎,这个需要安装 dot/graphviz , 我的配置在linux 的默认路径,不需要特别配置,这里留空
planuml_jar_path: 如果需要UML输出,需要告诉doxygen 插件位置,这个插件很多产品都有,我指向了Pycharm :wq
生成文档
保存配置后,运行 doxygen cpp-template , 视项目规模和输出内容丰富程度,几秒或者更长时间文档就会生成在当前目录下的 html 文件夹(如果不存在则创建),也可以指定输出位置。
以上就是html 目录内容, 不要在此停留,此时你有2个选择:
打包拿到本地,用浏览器打开 html/index.html
放到www服务器,如同正常网站一样发布,让团队的人都可以访问到
主页面
类视图
类协作图是dot 自动生成的
函数视图
调用和被调关系是 dot 自动生成的
像老手一样用doxygen
按照上述3个步骤,可以在几分钟内获得一份基础文档。
为什么说基础呢,这个文档是通过代码解析+原始注释抽取获得的,如果完全没注释或者注释很少,提取的就全部是底层的机器逻辑,从信息上说和你直接看代码没区别,只是它极大加速了这个过程。下面是一些更好使用doxygen 的技巧。
按照标准模板注释,可以帮助doxygen 更准确生成文档。零注释是可以的,但是生成的都是底层逻辑。
大工程有很多优化配置,比如分多层子目录,缓存设置,调用链长度限制
调用latex 生成更本地化的文档, 也可以生成带索引的chm 文件
用 pre-commit 将 doxygen 文档刷新和 git 提交绑定,每次文档和代码同步更新
将html 链接到服务器 html 目录, 文档-代码-网站同步
用include, exclude, suffix 参数精细控制文档范围
- 点赞
- 收藏
- 关注作者
评论(0)