doxygen 5分钟

举报
oneliner 发表于 2020/11/20 10:21:39 2020/11/20
【摘要】 请用5分钟阅读本文,然后立即投入实践,养成良好的文档习惯,你将节约无数宝贵的屎山打滚时间。

请用5分钟阅读本文,然后立即投入实践,养成良好的文档习惯,你将节约无数宝贵的屎山打滚时间。


先澄清几个误区:

  1. doxygen 不是写文档的:文档还是要自己写,doxygen 是抽取文档并展示、索引的工具

  2. 我的屎山项目没文档,doxygen 对我没用:现在是你最需要doxygen 的时候,它可以通过代码解析生成一份超出你预期的基础文档

  3. 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个选择:

  1. 打包拿到本地,用浏览器打开 html/index.html 

  2. 放到www服务器,如同正常网站一样发布,让团队的人都可以访问到



主页面


类视图

类协作图是dot 自动生成的



函数视图

调用和被调关系是 dot 自动生成的


像老手一样用doxygen

按照上述3个步骤,可以在几分钟内获得一份基础文档。 

为什么说基础呢,这个文档是通过代码解析+原始注释抽取获得的,如果完全没注释或者注释很少,提取的就全部是底层的机器逻辑,从信息上说和你直接看代码没区别,只是它极大加速了这个过程。下面是一些更好使用doxygen 的技巧。


  • 按照标准模板注释,可以帮助doxygen 更准确生成文档。零注释是可以的,但是生成的都是底层逻辑。

  • 大工程有很多优化配置,比如分多层子目录,缓存设置,调用链长度限制

  • 调用latex 生成更本地化的文档, 也可以生成带索引的chm 文件

  • 用 pre-commit 将 doxygen 文档刷新和 git 提交绑定,每次文档和代码同步更新

  • 将html 链接到服务器 html 目录, 文档-代码-网站同步

  • 用include, exclude, suffix 参数精细控制文档范围


【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。