玩转doxygen 之RT-THREAD

发布于 2022-08-04 22:57:23 浏览：1987 订阅该版

[tocm]

# 玩转doxygen 之RT-THREAD
这个论坛文章发了有点怪怪的。
原文链接：
https://blog.csdn.net/lt6210925/article/details/126167802

# 玩转doxygen 之RT-THREAD

## 文章目标

经常会看到小伙伴们遇到怎么写函数注释头疼，以及如何生成漂亮的代码注释文档头疼。据我了解，目前C语言中的代码注释规则有且只有一种比较常用，就是doxygen。所以掌握doxygen，对于我们写出漂亮的注释，至关重要。本文就教大家如何写doxygen，以及在RT-THREAD上如何整理出漂亮的API说明文档。

## 如何在RT-THREAD上生成doxygen

先教大家怎么操作，最近正好我整理了一下，发现RT-THREAD上面的doxygen

`https://github.com/RT-Thread/rt-thread/tree/master/documentation/doxygen`

生成不了文档，有些路径已经变掉了。所以帮大家修复了一下。

`https://github.com/RT-Thread/rt-thread/pull/6217`

现在大家只要下载最新的代码2022.8.4号之后的代码就可以了。

### 下载代码和软件

- 首先将rt-thread的源码`https://github.com/RT-Thread/rt-thread/`  下下来，可以用下面的命令

```
git clone git@git.zhlh6.cn:RT-Thread/rt-thread.git --depth=1
```

- 下载doxygen的软件（在doxygen文件夹中的readme.md）`https://doxygen.nl/index.html`

下载step安装包就行doxygen-1.9.4-setup.exe

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/e8c46d793b55c33e9b8b8cf8f2125a03530ca96e.png#pic_center)

- 安装doxygen，安装的时候没有什么需要注意的，直接下一步下一步就可以了。

### 生成html文档

我们打开刚才安装的软件`Doxywizard`

在菜单`File`中`Open` 打开刚才下的RT-THREAD中的如下文件`rt-thread/documentation/doxygen/Doxyfile`

然后直接运行`run` 就可以了，所有操作完成。

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/1575f05bb517888bc75c68165a29f3409c7eb9c4.png#pic_center)

如果想看中文，也可以根据下面的设置来选择中文

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/a3f519b691a49b4f123ebb254787edf20ca576f3.png#pic_center)

### 打开html文档

找到生成的`html`文件夹打开`index.html`文件就可以了

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/7daac7741f3ee6a2de9edc8341b23236e334d9ae.png#pic_center)

### 展现效果

接下来我们就可以看到效果图了，可以看到很多src目录下面大家写的一些注释

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/1fb9f4aaa5ee736afb28533c957605053bbb0332.png#pic_center)

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/423d8dd8d69f8d8f42d9bd4307c9d4c3624c029e.png#pic_center)

上面基本就是RT-THREAD的doxygen的使用方法了。是不是很简单，很方便？

下面简单介绍下如何自己写doxygen。

##  Doxygen 如何写

### vscode 插件安装

我们先讲讲doxygen怎么写。传统方法直接用文本编辑器来写，这个我这边就不多介绍了。这边我们用一个工具来帮助我们来写常用的doxygen。打开vscode， 安装插件doxygen

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/d752e5047022911b4fd00cec6b3bac7bd546ca8c.png#pic_center)

这个插件一共有两种操作

- 在源码文件中头部输入·`/**`  ，然后直接按回车键，你可以看到自动生成的注释了。

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/62f7862117c262f67ef39b55affb4dae858e5c69.gif#pic_center)

- 在写好的函数的上面输入`/**` , 然后也是按回车键，你就看也看到效果了。

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/75a0eb7232dc341021e90e32b8a6fec5769372f1.gif#pic_center)

### doxygen文件生成

只要打开Doxygen工具，选择source 文件夹，之后点击`run` 就可以了

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/39432e7032fbad66a7259e56569aa461e4319faa.png#pic_center)

### doxygen配置

doxygen的配置其实有很多很多，这边我就举几个常用的配置。

下面的配置可以生成左侧的树状图，方便查看。其他的配置不一一介绍了。

想了解的可以参考链接

https://mp.weixin.qq.com/s/HA352TEBELNJ9pgCTMkWIg

![在这里插入图片描述](https://oss-club.rt-thread.org/uploads/20220818/ba6642dc1370c2156ac026a78836dfeb5b354397.png#pic_center)

### doxygen写的时候一些建议

#### 问题一： doxygen的函数注释写在头文件中还是源文件中？

这个因不同公司角色而已。如果你的代码是作为lib的话。.c是不开放给客户的，这个时候，写在.h中比较好。

如果你是做开源的，源文件可以开放出来，这个时候，放在.c里面比较好。总之，只要放一个地方就行，其他地方不需要按照doxygen来写。

### 如果你有其他问题，可以评论区留言，我会一一解答

18 条评论

wh_zhangll 2022-08-23

See through the appearance to perceive the essence.

WoodData 2022-09-16

这家伙很懒，什么也没写！

用户名由3_15位 2022-11-17

这家伙很懒，什么也没写！

刺刺赐 2022-11-17

大家吃好喝好

数码小叶 2022-11-19

这家伙很懒，什么也没写！

RWZZ_6063 2023-01-14

这家伙很懒，什么也没写！

RTT_逍遥 2023-01-14

https://github.com/supperthomas

RWZZ_6063 2023-01-14

这家伙很懒，什么也没写！

RWZZ_6063 2023-01-14

这家伙很懒，什么也没写！

RWZZ_6063 2023-01-14

这家伙很懒，什么也没写！

日志如下，谢谢
```
Doxygen version used: 1.9.4 (5d15657a55555e6181a7830a5c723af75e7577e2)
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for msc files...
Searching for dia files...
Searching for files to exclude
Searching INPUT for files to process...
Searching for files in directory D:/gitbase_api/rt-thread/documentation/doxygen
Reading and parsing tag files
Parsing files
Preprocessing D:/gitbase_api/rt-thread/documentation/doxygen/basicdef.h...
Parsing file D:/gitbase_api/rt-thread/documentation/doxygen/basicdef.h...
Preprocessing D:/gitbase_api/rt-thread/documentation/doxygen/filesystem.h...
Parsing file D:/gitbase_api/rt-thread/documentation/doxygen/filesystem.h...
Preprocessing D:/gitbase_api/rt-thread/documentation/doxygen/finsh.h...
Parsing file D:/gitbase_api/rt-thread/documentation/doxygen/finsh.h...
Preprocessing D:/gitbase_api/rt-thread/documentation/doxygen/hardware.h...
Parsing file D:/gitbase_api/rt-thread/documentation/doxygen/hardware.h...
Preprocessing D:/gitbase_api/rt-thread/documentation/doxygen/kernel.h...
Parsing file D:/gitbase_api/rt-thread/documentation/doxygen/kernel.h...
Preprocessing D:/gitbase_api/rt-thread/documentation/doxygen/mainpage.h...
Parsing file D:/gitbase_api/rt-thread/documentation/doxygen/mainpage.h...
Preprocessing D:/gitbase_api/rt-thread/documentation/doxygen/module.h...
Parsing file D:/gitbase_api/rt-thread/documentation/doxygen/module.h...
Reading D:/gitbase_api/rt-thread/documentation/doxygen/readme.md...
Preprocessing D:/gitbase_api/rt-thread/documentation/doxygen/systeminit.h...
Parsing file D:/gitbase_api/rt-thread/documentation/doxygen/systeminit.h...
Building macro definition list...
Building group list...
Building directory list...
Building namespace list...
Building file list...
Building class list...
Building concept list...
Computing nesting relations for classes...
Associating documentation with classes...
Associating documentation with concepts...
Building example list...
Searching for enumerations...
Searching for documented typedefs...
Searching for members imported via using declarations...
Searching for included using directives...
Searching for documented variables...
Building interface member list...
Building member list...
Searching for friends...
Searching for documented defines...
Computing class inheritance relations...
Computing class usage relations...
Flushing cached template relations that have become invalid...
Computing class relations...
Add enum values to enums...
Searching for member function documentation...
Creating members for template instances...
Building page list...
Search for main page...
Computing page relations...
Determining the scope of groups...
Sorting lists...
Determining which enums are documented
Computing member relations...
Building full member lists recursively...
Adding members to member groups.
Computing member references...
Inheriting documentation...
Generating disk names...
Adding source references...
Adding xrefitems...
Sorting member lists...
Setting anonymous enum type...
Computing dependencies between directories...
Generating citations page...
Counting members...
Counting data structures...
Resolving user defined references...
Finding anchors and sections in the documentation...
Transferring function references...
Combining using relations...
Adding members to index pages...
Correcting members for VHDL...
Computing tooltip texts...
Generating style sheet...
Generating search indices...
Generating example documentation...
Generating file sources...
Generating code for file basicdef.h...
Generating code for file filesystem.h...
Generating code for file finsh.h...
Generating code for file hardware.h...
Generating code for file kernel.h...
Generating code for file mainpage.h...
Generating code for file module.h...
Generating code for file systeminit.h...
Generating file documentation...
Generating page documentation...
Generating docs for page md_readme...
Generating group documentation...
D:/gitbase_api/rt-thread/documentation/doxygen/filesystem.h:15: warning: image file dfs.png is not found in IMAGE_PATH: assuming external image.
D:/gitbase_api/rt-thread/documentation/doxygen/finsh.h:15: warning: image file finsh.png is not found in IMAGE_PATH: assuming external image.
D:/gitbase_api/rt-thread/documentation/doxygen/kernel.h:64: warning: image file Kernel_Object.png is not found in IMAGE_PATH: assuming external image.
D:/gitbase_api/rt-thread/documentation/doxygen/kernel.h:65: warning: image file Kernel_Object.png is not found in IMAGE_PATH: assuming external image.
D:/gitbase_api/rt-thread/documentation/doxygen/kernel.h:157: warning: unable to resolve reference to '_rt_errno' for \ref command
Generating class documentation...
Generating concept documentation...
Generating namespace index...
Generating graph info page...
Generating directory documentation...
Generating index page...
D:/gitbase_api/rt-thread/documentation/doxygen/mainpage.h:29: warning: image file System_Arch.png is not found in IMAGE_PATH: assuming external image.
D:/gitbase_api/rt-thread/documentation/doxygen/mainpage.h:29: warning: image file System_Arch.png is not found in IMAGE_PATH: assuming external image.
Generating page index...
Generating module index...
Generating namespace index...
Generating namespace member index...
Generating concept index...
Generating annotated compound index...
Generating alphabetical compound index...
Generating hierarchical class index...
Generating member index...
Generating file index...
Generating file member index...
Generating example index...
finalizing index lists...
writing tag file...
Running plantuml with JAVA...
lookup cache used 10/65536 hits=0 misses=10
finished...
*** Doxygen has finished
```