程序员经验分享-hwhale

代码文档生成工具Doxygen教程及实例

2023-05-16

程序员的很多文档，特别是有代码的文档，绝大部分都是由一款文档生成工具【Doxygen】生成。

什么是Doxygen?

Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。
大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用你的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于你来说，就是沉重的负担。
简而言之，Doxgen就是大名鼎鼎的文档生成工具，而且是免费开源的，它使用非常方便，能提取C++，Java，Objective-C，Python，IDL，PHP，C#等语言的注释，从而生成文档。
Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来生成文档。
在Linux下可以通过apt install doxygen安装命令行工具，然后用apt install doxygen-gui安装图形界面。
对Linux用户来说，命令行工具可以通过doxygen命令运行，而图形界面可以通过doxywizard命令运行。
Windows 用户的下载地址：http://www.doxygen.nl/download.html
2、基本使用
图形工具的基本使用如下图所示，有非常多的配置选项，这里我们只填入必要的配置，其它配置都用默认值。

图片

doxywizard使用步骤

图片

doxywizard使用步骤

工作目录如下：

.
├── out
└── src
    └── math.h

其中math.h代码如下：

/*! \file math.h */

/*!
    用于求一个角度的sin值，输入是字符串以便同时支持弧度制和角度制表示
    \li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角
    \li 角度制用d结尾，例如：360d表示一圈、90d表示直角
    \li 输入也可以是数值，例如：输入3.14159大约表示180度

    \param a 用弧度制或角度制表示都行，字符串必须用'\0'表示结束
    \param[out] res 是输出参数，用于保存sin运算的结果

    \return 错误码，0表示成功，其它表示失败

    \todo 在xxx的情况下存在BUG，预计下一版本修复
*/
int sin(char *a, double *res);

Doxygen生成的HTML会放到out目录下，生成的HTML如下图所示。

图片

HTML界面

3、保存配置
上面我们配置了一些选项，也成功生成了HTML文档。我们希望下次代码改动后能够继续沿用上次配置，那么我们可以把这些配置保存成Doxyfile文件，如下图所示。

图片

保存Doxyfile配置文件

有了配置文件后我们完全可以通过命令行来生成API文档，假设配置文件名为Doxyfile，那么我们只需要执行doxygen /path/to/Doxyfile即可生成API文档。
通过命令行生成文档有许多好处，其中最主要的好处就是：能够集成到持续集成之类的自动化系统中。

1.什么样的注释会被Doxygen识别？
Doxygen能识别这几种风格的注释：

/**
 * ... text ...
 */

/*!
 * ... text ...
 */

///
/// ... text ...
///

//!
//!... text ...
//!

文件的开头必须有文件注释，否则该文件不会被识别：

/*! \file math.h */

2.注释怎么写
这里建议参考官网例子。https://www.doxygen.nl/manual/doxygen_usage.html

Doxygen主要支持C语言，其它语法跟C差不多的语言（如：C++/C#/PHP/Java）也能够支持，我们称这类语言为「C语系语言」。而哪些跟C语法差异较大的语言叫做「非C语系语言」。
对于大多非C语系语言，Doxygen都是支持的，Doxygen原生支持这些语言：IDL、Java、Javascript、C#、C、C++、D、PHP、Objective-C、Python、Fortran、VHDL。
万一项目需要的语言（例如：Lua）Doxygen官方并不支持，那么只能自行编写「第三方语言扩展」来支持了。
1.Doxygen官方支持的语言见下图，文件名符合FILE_PATTERNS都会被处理。其中包括了.c、.h、.py等等。

图片

如果我们的扩展名并不在FILE_PATTERNS内，那么可以加上去。例如我们项目下的所有.ccc文件，其实是C语言代码（这很奇葩，举个例子而已）。那我们可以编辑Doxyfile配置文件满足这一需求，需要2个步骤。
(1) 在FILE_PATTERNS中添加*.ccc，如下图：

图片

(2) 在EXTENSION_MAPPING中添加映射规则ccc=C，如下图，语法是ext=language，其中language可以取的值有：IDL、Java、Javascript、C#、C、C++、D、PHP、Objective-C、Python、Fortran、VHDL。

图片

2.Doxygen官方不支持的语言
以Lua语言为例，它的代码是长这样的：

-- \file lmath.h
--[[    用于求一个角度的sin值，输入是字符串以便同时支持弧度制和角度制表示    \li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角    \li 角度制用d结尾，例如：360d表示一圈、90d表示直角    \li 输入也可以是数值，例如：输入3.14159大约表示180度
    \param a 字符串类型，表示角度，用弧度制或角度制表示都行
    \return 返回sin运算的结果
    \todo 在xxx的情况下存在BUG，预计下一版本修复--]]function sin(a)    return 1.123end

可以看到Lua的语法既不像C也不像Python。
本文就分享到这里，更详细的使用教程可以查看官方文档：

https://www.doxygen.nl/manual/doxygen_usage.html

转载于：https://mp.weixin.qq.com/s/XfaP6DF5G6lgXRJo8XAV2Q

如果只有一个没有注释的文件文件，一个没有注释的函数

image-20220429174231889

#include <stdio.h>

int main(void) {
    printf("Hello World!\n");
}

最后产生的文档则是啥也没有。

还是一个源文件，文件有注释，函数也有两个，函数也都有注释

/**
  * @file     	main.c
  * @author   	JonesLee
  * @email   	Jones_Lee3@163.com
  * @version	V4.01
  * @date    	07-DEC-2017
  * @license  	GNU General Public License (GPL)  
  * @brief   	Universal Synchronous/Asynchronous Receiver/Transmitter 
  * @detail		detail
  * @attention
  *  This file is part of OST.                                                  \n                                                                  
  *  This program is free software; you can redistribute it and/or modify 		\n     
  *  it under the terms of the GNU General Public License version 3 as 		    \n   
  *  published by the Free Software Foundation.                               	\n 
  *  You should have received a copy of the GNU General Public License   		\n      
  *  along with OST. If not, see <http://www.gnu.org/licenses/>.       			\n  
  *  Unless required by applicable law or agreed to in writing, software       	\n
  *  distributed under the License is distributed on an "AS IS" BASIS,         	\n
  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  	\n
  *  See the License for the specific language governing permissions and     	\n  
  *  limitations under the License.   											\n
  *   																			\n
  * @htmlonly 
  * <span style="font-weight: bold">History</span> 
  * @endhtmlonly 
  * Version|Auther|Date|Describe
  * ------|----|------|-------- 
  * V3.3|Jones Lee|07-DEC-2017|Create File
  * <h2><center>&copy;COPYRIGHT 2017 WELLCASA All Rights Reserved.</center></h2>
  */  

#include <stdio.h>

/**
 * @brief hhhhh,this is a test file.
 * 
 * @return int 
 */
int add(int a, int b) {
    return a+b;
}

int main(void) {
    printf("Hello World!\n");
}

最后生成的文档如下图：

image-20220429180227347

image-20220429180150214

https://raw.githubusercontent.com/xkyvvv/blogpic3/main/image-20220429181945825.png

有多个源文件，每个文件有多个函数

在这里插入图片描述

main.c

/**
  * @file     	main.c
  * @author   	JonesLee
  * @email   	Jones_Lee3@163.com
  * @version	V4.01
  * @date    	07-DEC-2017
  * @license  	GNU General Public License (GPL)  
  * @brief   	Universal Synchronous/Asynchronous Receiver/Transmitter 
  * @detail		detail
  * @attention
  *  This file is part of OST.                                                  \n                                                                  
  *  This program is free software; you can redistribute it and/or modify 		\n     
  *  it under the terms of the GNU General Public License version 3 as 		    \n   
  *  published by the Free Software Foundation.                               	\n 
  *  You should have received a copy of the GNU General Public License   		\n      
  *  along with OST. If not, see <http://www.gnu.org/licenses/>.       			\n  
  *  Unless required by applicable law or agreed to in writing, software       	\n
  *  distributed under the License is distributed on an "AS IS" BASIS,         	\n
  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  	\n
  *  See the License for the specific language governing permissions and     	\n  
  *  limitations under the License.   											\n
  *   																			\n
  * @htmlonly 
  * <span style="font-weight: bold">History</span> 
  * @endhtmlonly 
  * Version|Auther|Date|Describe
  * ------|----|------|-------- 
  * V3.3|Jones Lee|07-DEC-2017|Create File
  * <h2><center>&copy;COPYRIGHT 2017 WELLCASA All Rights Reserved.</center></h2>
  */  

#include <stdio.h>

/**
 * @brief hhhhh,this is a test file.
 * 
 * @return int 
 */
int add(int a, int b) {
    return a+b;
}

/**
 * @brief sub function
 * 
 * @return int 
 */
int sub(int a, int b) {
    return a-b;
}

/**
 * @brief xkyzzz
 * 
 * @return int
 */
int main(void) {
    printf("Hello World!\n");
}

module.c

/**
  * @file     	module.c
  * @author   	xky
  * @email   	Jones_Lee3@163.com
  * @version	V4.01
  * @date    	07-DEC-2017
  * @license  	GNU General Public License (GPL)  
  * @brief   	Universal Synchronous/Asynchronous Receiver/Transmitter 
  * @detail		detail
  * @attention
  *  This file is part of OST.                                                  \n                                                                  
  *  This program is free software; you can redistribute it and/or modify 		\n     
  *  it under the terms of the GNU General Public License version 3 as 		    \n   
  *  published by the Free Software Foundation.                               	\n 
  *  You should have received a copy of the GNU General Public License   		\n      
  *  along with OST. If not, see <http://www.gnu.org/licenses/>.       			\n  
  *  Unless required by applicable law or agreed to in writing, software       	\n
  *  distributed under the License is distributed on an "AS IS" BASIS,         	\n
  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  	\n
  *  See the License for the specific language governing permissions and     	\n  
  *  limitations under the License.   											\n
  *   																			\n
  * @htmlonly 
  * <span style="font-weight: bold">History</span> 
  * @endhtmlonly 
  * Version|Auther|Date|Describe
  * ------|----|------|-------- 
  * V3.3|Jones Lee|07-DEC-2017|Create File
  * <h2><center>&copy;COPYRIGHT 2017 WELLCASA All Rights Reserved.</center></h2>
  */  
 

/**
 * @brief 
 * 
 */
void mFun1(void)
{
    ;
}

/**
 * @brief 
 * 
 */
void mFun2(void)
{
    ;
}

生成文档如下图：

image-20220429183830257

https://raw.githubusercontent.com/xkyvvv/blogpic3/main/image-20220429183938826.png

image-20220429184003292

image-20220429184022485

image-20220429184052826

image-20220429184109931

通过上面这些测试，我们应该可以知道如何去使用这个软件。下面我以一个实际项目的源码来测试一下。

测试的代码是RT-Thread的源码，地址：https://github.com/RT-Thread/rt-thread

源码目录：

在这里插入图片描述

生成文档如下图：

image-20220429193525371

本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)

Doxygen

代码文档生成工具

教程及实例

代码文档生成工具Doxygen教程及实例 的相关文章

  • Doxygen使用教程（个人总结）

    简介Doxygen 一 xff0e 什么是Doxygen Doxygen 是一个程序的文件产生工具 xff0c 可将程序中的特定批注转换成为说明文件 通常我们在写程序时 xff0c 或多或少都会写上批注 xff0c 但是对于其它人而言 xf

  • 代码文档生成工具Doxygen教程及实例

    程序员的很多文档 xff0c 特别是有代码的文档 xff0c 绝大部分都是由一款文档生成工具 Doxygen 生成 什么是Doxygen Doxygen 是一个程序的文件产生工具 xff0c 可将程序中的特定批注转换成为说明文件 通常我们在

  • 未解决的外部噩梦

    各位行业资深人士 大家好 我是一名大三学生 即将开始我的第一次暑期编程实习 但我的能力已经超出了我的能力范围 我工作的公司从另一家公司购买了一个庞大的应用程序 该公司自 90 年代初以来一直在慢慢扩展和修改它 该解决方案包含超过 200 0

  • Roxygen 真的可以像 Doxygen 对 C++ 那样记录 R 脚本（而不是包）吗？

    Roxygen 的灵感来自 C C 程序员使用的 Doxygen 文档系统 我使用过 Doxygen 我发现只要有 doxygen 注释 记录任何程序都非常容易 它还生成函数和类的调用图 我认为 roxygen 会以同样的方式工作 但是当我

  • 有没有办法使用 doxygen 记录 cuda 的“.cu”文件

    由于cuda的 cu 文件基本上是c 有没有办法我们可以使用doxygen为 cu 文件生成文档 我注意到 NVIDIA 使用 doxygen 来生成 cuda 的文档 但是 当我使用 doxygen 时 cu 文件将被忽略 如果其他人也遇

  • Doxygen 在记录 PHP 时出现奇怪的问题 if

    当我尝试记录我的项目时 我遇到了一个奇怪的问题 我有以下代码 Set default action for called controller If no action is called default index will be set

  • 在 .NET 中使用 XML 注释有哪些优点？

    我无法理解使用 XML 注释的优点 我知道它们可以转换为代码外部的漂亮文档 但使用更简洁的 DOxygen 语法也可以实现同样的效果 我认为 XML 注释是错误的 因为 他们总体上混淆了注释和代码 它们更难被人类阅读 在单个屏幕上可以查看的

  • Doxygen - 将参数声明为可选

    我正在使用 Doxygen 记录代码库 并且想知道是否有一个关键字用于将函数的参数声明为可选 就像是 fn int add int a int b 0 brief adds two values param a the first oper

  • 在 doxygen 输出中隐藏公共包

    给定一些包foo bar project something FirstModule foo bar project something SecondModule等等 他们都有那么长foo bar project something共同点

  • 从 Shell 输出生成文档

    有没有一种方法 工具可以直接从我的 Shell 输出甚至保存的日志生成 HTML 文档 类似于 doxygen 的作用 如果没有可用的东西 你们对如何使用现有工具做到这一点有什么创意吗 我想 在打字时 我可以放置某种标记或特殊字符 然后让一

  • 我可以在函数头中包含 cppcheck 抑制吗？

    我添加了一个内联注释来抑制函数的 cppcheckusedFunction 警告 但我想将其包含在函数头中 以便 Doxygen 可以记录所有未使用的函数 我正在实现一个 API 所以我有很多函数不会在我的源代码中使用 我不想抑制所有未使用

  • python 中的 Doxygen C++ 注释字符串解析器？

    有人知道有一个 python 模块可以解析 doxygen 风格的 C 注释字符串吗 我的意思是像这样的字符串 简单的例子 A constructor A more elaborate description of the construc

  • 我应该如何记录继承的成员？ [关闭]

    Closed 这个问题是基于意见的 help closed questions 目前不接受答案 考虑一下我有一个复杂的类结构 其中许多元素继承自其他元素 我可能有一个方法GetStuff string stuffName int count

  • Doxygen copydoc 标签可重用代码示例

    我想使用 copydoc 标签重用示例代码块 来解释一下问题 假设我有两个已记录的函数 Aquires resource Resource AquireResource int id Releases resource void Relea

  • 如果我使用 DOT 和 doxygen，如何更改由 graphviz 创建的图表在 HTML 中的位置？

    我在 doxygen 中使用 dot 和 Graphviz 以 HTML 格式创建代码的用户手册 doxygen 代码看起来有点像这样 br addtogroup MainProgram dot digraph G Main label M

  • Visual Studio 自动完成 C++ 的 Doxygen 标签

    有没有办法让 Visual Studio 自动将 doxygen 标签放入 C 源文件中 我的意思是例如这段代码 int foo bool p 如果我输入 在其之上 Visual Studio 自动生成以下行

  • 使用 Doxygen 自定义标签

    我想弄清楚是否有办法使用 Doxygen 创建自定义标签 我确实找到了 ALIAS 配置文件选项 但这并不完全符合我的需要 基本上在我的代码中我希望能够编写类似的内容 req Requirement 322 blah blah 然后让 Do

  • Doxygen：在“相关页面”部分下添加自定义链接

    我有几个 html 页面解释了我的代码的不同部分 并且我最近也在其上运行了 Doxygen 我想在 Doxygen 的 相关页面 页面下添加指向我当前 html 页面的链接 除了手动插入之外 还有其他方法可以做到这一点吗 看看多氧 page

  • 是否存在用于编辑 doxygen 评论的“wiki”？ [关闭]

    Closed 此问题正在寻求书籍 工具 软件库等的推荐 不满足堆栈溢出指南 help closed questions 目前不接受答案 我正在开发一个相当大的开源 RTS 游戏引擎 Spring http springrts com 我最近

  • 如何记录 Doxygen 中不存在的变量？

    例如 我在配置文件中定义了 theme 全局变量 Doxygen 不处理该变量 但我想记录下来 我尝试这样做 var theme brief Active theme 但没有成功 您可以创建一个 doxygen 特定文件来记录变量 例如 配

随机推荐

  • 【C/C++开源库】单片机/嵌入式中的C语言日志库

    日志系统在系统开发和调整过程中的重要性 xff0c 大家应该都清楚 xff0c 特别是项目出问题之后 xff0c 却没有日志可以帮忙定位问题 xff0c 就非常令人痛苦 因为我们不可能一直通过调试器去单步调试程序 xff0c 所以设备的运行

  • 稚晖君软件硬件开发环境总结

    0 引言 这两天在bilibili上发现一个宝藏up主 xff0c 稚晖君 啧啧啧 xff0c 很厉害 虽然年龄不大 xff0c 但是真全栈 xff0c 从产品到机械到电路到软件 xff0c 这就是那种真的聪明 xff0c 一学就会的高智商

  • 一文弄清51、STM32、Linux点灯的区别

    嵌入式初学者入门的第一个 项目 就是LED点灯 xff0c 那么 xff0c 本文带你看看51 STM32 Linux点灯有什么区别 xff1f 51点灯 51点灯 xff0c 是很多单片机初学者的首选 xff0c 难度也是相对比较低的 准

  • Keil 模拟器 STM32F103 上手指南

    一般嵌入式操作系统因为它的特殊性 xff0c 往往和硬件平台密切相关连 xff0c 具体的嵌入式操作系统往往只能在特定的硬件上运行 对于刚接触 RT Thread 操作系统的读者并不容易马上就获得一个和 RT Thread 操作系统相配套的

  • 用PyOD工具库进行「异常检测」

    转载于知乎 xff1a 微调 异常检测 xff08 又称outlier detection anomaly detection xff0c 离群值检测 xff09 是一种重要的数据挖掘方法 xff0c 可以找到与 主要数据分布 不同的异常值

  • 在Keil 模拟器上测试RT-Thread代码

    前面一篇文章已经讲解了如何使用Keil模拟器来模拟硬件 xff0c 然后在此基础上运行RT Thread代码 文章链接 xff1a Keil 模拟器 STM32F103 上手指南 我们可以看到RT Thread官方有许多代码示例供我们学习参

  • 在这个艰难的环境下，我裸辞了

    2022年 xff0c 疫情期间 xff0c 工作了22年的我 xff0c 从软件研发管理的相关工作中 xff0c 辞职创业 xff0c 开启我的独立咨询顾问生涯 很多人不解和迷惑 xff0c 也有朋友关切的询问我的近况 xff0c 就差用

  • 2022年顶级实时操作系统榜单发布

    全球知名的开源软件仓库平台SourceForge最近公布了一份 2022年顶级实时操作系统 xff08 RTOS xff09 榜单 其中包括大家熟悉的FreeRTOS RT Thread ThreadX embOS等实时操作系统 地址 xf

  • IDE也卷了，微软杀入嵌入式IDE

    为什么说 IDE 也卷了 xff1f 因为前不久 xff08 3月初 xff09 xff0c Keil 官方推出了免费 没有代码大小限制的社区版IDE xff08 Community xff09 随后 xff08 在上周 xff09 xff

  • 飞机上一般是什么操作系统？

    航空软件其实并不神秘 xff0c 从计算机架构上来说 xff0c 同普通的计算机系统并无太大区别 xff0c 都是由处理器 总线 I O设备 存储设备 网络设备 通讯设备 操作系统和应用软件所构成的 仅仅是为了满足很高指标的可靠性 健壮性和

  • 重构代码总结

    下面推荐一下进行代码重构的文章 xff1a 重构指北 重构 xff0c 改善既有代码设计 精读 经验总结 重构让你的代码更优美和简洁 常见代码重构技巧 如何实施代码重构 xff1f 代码重构新手教程 xff1a 如何将烂代码变成好代码 xf

  • C语言#和##的使用方法和宏嵌套

    推荐下面几篇好文 xff1a C语言 宏嵌套的展开规则 C语言中define的全部使用方法总结 C语言宏的定义和宏的使用方法 xff08 define xff09 C语言宏定义中 与 的用法

  • 深入PCI与PCIe

    转载于老狼 xff1a https zhuanlan zhihu com p 26172972 https zhuanlan zhihu com p 26244141 PCI总线和设备树是X86硬件体系内很重要的组成部分 xff0c 几乎所

  • 【程序员学理财】了解不同理财产品的利息及合理的选择自己的理财配置

    1 利息计算公式 利息计算公式 2 不同理财产品的利率 首先是银行相关的理财 xff1a 余额宝利率 xff1a 年利率在1 94 支付宝短期定期理财 xff1a 一个月利率 xff1a 3 3 xff1b 三个月利率 xff1a 3 9

  • 嵌入式设备系统有无操作系统的区别

    随着通信 电子物联网的飞速发展 xff0c 每天都有各种各样的芯片被研发出来 xff0c 而要想知道这些芯片怎样工作以及工作后的作用 xff0c 则离不开软硬件工程师的努力 xff0c 任何一个计算机系统都是系统中软硬件协作的结果 xff0

  • 从C语言来理解文件系统

    文章目录 一 文件 文件系统二 C语言文件操作详解C语言中的文件是什么 xff1f 文件流 C语言fopen函数的用法 xff0c C语言打开文件详解fopen 函数的返回值判断文件是否打开成功 fopen 函数的打开方式关闭文件实例演示

  • 如何把CPP源程序改写成C语言？

    转载于 xff1a https mp weixin qq com s Xk5k UAItEndEGrUsQr Yw 曾经参与过公司的bpp项目 xff0c 就是bluetooth print profile 由于使用了hpijs的开源包 x

  • Android源码学习之六——ActivityManager框架解析

    ActivityManager 在操作系统中有重要的作用 xff0c 本文利用操作系统源码 xff0c 逐步理清 ActivityManager 的框架 xff0c 并从静态类结构图和动态序列图两个角度分别进行剖析 xff0c 从而帮助开发

  • 怎样修改Ubuntu&windows10双系统的默认启动顺序

    怎样修改Ubuntu amp windows10双系统的默认启动顺序 参考网址 xff1a https jingyan baidu com article f71d60379e16021ab641d1ab html 很多人在安装Linux系

  • 代码文档生成工具Doxygen教程及实例

    程序员的很多文档 xff0c 特别是有代码的文档 xff0c 绝大部分都是由一款文档生成工具 Doxygen 生成 什么是Doxygen Doxygen 是一个程序的文件产生工具 xff0c 可将程序中的特定批注转换成为说明文件 通常我们在

热门标签