1. 摘要
本文档主要用来指导和建议工程师如何写好软件代码的注释,方便使用Doxygen生成文档
2. 准备工作
安装Doxygen软件
正常的代码工程
3. 实施
好的注释习惯,往往会为你节省很多时间,不管是给自己以后阅读代码还是给别人都是一种良好的开发习惯,而按照一定的规则注释,还可以利用工具直接生成文档,方便代码审阅或者联合开发。Doxygen就是开发中广发使用的工具,如果你留意的话,很多的源码包都是使用Doxygen来生成代码文档,如下图就是我使用Doxygen为工程生成的文档中的一个文件展示
而生成这样的文档,注释就要按照Doxygen的规则,注释就要按照类似如下的格式来书写
更多的书写规则可以参考Doxygen的手册文档,https://www.doxygen.nl/manual/index.html
每一章都讲解的很详细,从安装到开始使用,可以说是step by step。
如果你记不住没关系,,可以多翻阅,这些规则都有例子,或者参阅一些源码包的注释,如我们来看一些源码包中的注释风格:
如lwip 协议栈源码包中的就是按照doxygen来注释的,只要运行相应文件就可以生成文档。
可以看到注释风格就是Doxygen 要求的。同样在其他一些常用的源码包里,大部分都是使用了doxygen来生成相应的文档。这样整个项目的结构和接口都会生成一个详细的文档,可以支持不同格式。大大方便了工作汇报,代码审阅评审,以及联合开发的接口沟通。所以大大推荐采用Doxygen的格式来写注释。尤其现在对中文的支持也越来越好了。