工具应用—Doxygen文档工具的应用

一、文档工具和Doxygen在实际的开发中写文档是最让开发者抵触的。对于大多数的开发者来说写代码比写文档要感觉爽很多。但在实际的开发过程中文档又是必不可少的。且不说给协作者提供相关的接口文档公司但凡正规一些要过一些标准或者拿什么资格都是需要提供大量的文档的。这些文档中涉及到具体的开发者的说明文档不同的语言又有不同的文档工具推荐比如Javadoc、Doxygen等。还有的开发者可能用过一些接口管理文档如OpenAPI‌和ShowDoc等。这些文档形形色色应用非常广泛。但对于C来说Doxygen是一个不错的文档工具。Doxygen作为一个强大的开源工具它能从源代码中依照规定格式的注释里自动提取信息并生成专业的文档比如常见的HTML、PDF等。利用Doxygen可以让开发者从厌烦的文档抽取编写工作中跳出来只专注于代码开发本身实现所谓的良好的代码注释即可。二、下载和安装Doxygen可以安装在Windows、Linux和Mac等主流的开发平台上。下面对其在Ubuntu22.04中的安装进行简单的说明其它平台的安装也非常简单。去官网下载安装包打开官网“https://www.doxygen.nl/download.html”下载相关的压缩包解压缩即可使用。当然为了方便可以将其注册到环境变量或直接拷贝到本地可执行目录下/usr/local/bin使用apt安装使用命令“sudo apt install doxygen”进行安装安装成功即可使用安装相关工具为了能够更好的使用Doxygen可以安装Graphviz用于可视化和LaTeX用于生成高质量的PDF安装方法为“sudo apt install graphviz”和“sudo apt install texlive-full”基本上按照上述的流程安装后就可以使用Doxygen。三、环境配置和整体操作流程在使用Doxygen进行文档处理前需要进行一些相关的环境设置主要包括生成工程配置文件打开命令窗口终端进入工程的根目录运行“doxygen -g”自动生成一个名称为Doxyfile的默认的配置文件。这个文件用来进行文档相关的编辑实现。编辑工程配置文件打开上面生成的Doxyfile文件修改其中的几个关键选项PROJECT_NAME项目名称PROJECT_NUMBER版本号INPUT指定源代码的目录RECURSIVE设为YES表示Doxygen递归处理INPUT目录下的子文件夹OUTPUT_DIRECTORY指定生成文档的输出目录编译代码中的注释即在代码中使用相关规则来编写注释利用Doxygen生成文档在完成上述操作后在命令行中输入“doxygen”即可读取Doxyfile中的配置并生成文档Reivew文档并反馈修改在指定的输出目录下查看生成的相关文档并根据实际要求结果加以完善和修改并再次执行生成交付使用Review并反馈迭代的最终文档就可以交付给相关方使用了Doxygen文档工具应用起来还是比较方便的但这就需要开发者把注释写得清晰准确不能想当然的编写注释或者干脆不写注释。四、工程应用Doxygen支持多种语言所以也支持多种的注释风格。常见的一般就是Javadoc和Qt风格以及简单的C风格。可以理解为如何启动注释与Doxygen交互的接口。下面简要说明一下JavaDoc风格这种风格一般和C语言的注释风格类似即“/** * brief 函数说明 */”Qt风格这种风格一般是以符号“”开头即“/*! * brief 函数说明 */”简单的C风格这种风格一般以“///”或“//”开始即“/// brief 函数说明 或 //! brief 函数说明”Doxygen中的注释块中一般是以“”或“\”开头来标记特定的内容。Doxygen将命令分成了几类文件结构和描述相关命令函数和逻辑命令代码显示和布局命令状态与维护命令常用的注释命令如brief: 基础的命令用于描述一个函数、类或变量的基础说明param: 对函数参数和相关内容进行说明return: 函数返回值的描述file: 代码源文件的注释说明一般用于文件头部see: 指示对其他部分引用的相关“参见”其它还有很多如基础的author作者date(日期)note(注解)post,pre(前后置条件)等等。这个没有什么难度看看文档说明就会了。下面看一个简单的例子/** * brief 计算整数和 * * 通过一个加法函数来举例说明Doxygen命令 * * param[in] a 第一个整数 * param[in] b 第二个整数 * return 返回a和b和 * * note 不支持浮点数运算 * warning 有可能整数溢出 * * code * int ret add(1, 6); * // ret 将是7 * endcode * * see subtract() * author 开发者 * version 0.1 */intadd(inta,intb){returnab;}五、问题和说明使用Doxygen在生成中文文档时如果出现乱码请将源代码文件和配置文件修改为使用UTF-8编码并将Doxyfile中的 OUTPUT_LANGUAGE设置为Chinese。一般情况下都会解决乱码的问题。另外在注释进行完善和修改后只需保存后在命令行中重新运行doxygen即可自动进行更新。在Doxygen可以通过简单的class和相关的继承命令如extends等来实现类等的关系图。如果启用了GRAPHICAL_HIERARCHY和HAVE_DOT则可以使用前面安装的Graphviz来生成类图。同样如查在配置中使用了UML_LOOK和 HAVE_DOT则也可以生成UML风格的协作图。可见Doxygen工具的功能还是非常强大的如果想使用好这个工具还需要开发者仔细的学习相关的说明文档在前面的下载地址中有相关说明文档的下载。本文对Doxygen工具的说明是一个极简的入门说明目的很简单就是让开发者能够迅速的明白Doxygen的作用和简单应用从而可以有步骤的在实践中引入相关的文档开发节省开发时间和编写文档的烦恼。六、总结从目前的编程的发展来看对开发者如何使用工具的要求是越来越高。反而对具体的语言的特性和技巧的要求不断在降低。特别是随着AI的应用以后更多的是需要开发者对业务和逻辑的控制而非是技术能力的展示。或者说技术能力的展示转到了后台用来监督工具的应用的结果。