Play RT-THREAD of doxygen

Article Objectives

We often see the headaches of how to write function comments and how to generate beautiful code comment documents.As far as I know, there is one and only one commonly used code comment rule in C language, which is doxygen.So mastering doxygen is crucial for us to write beautiful comments.This article will teach you how to write doxygen and how to organize beautiful API documentation on RT-THREAD.

How to generate doxygen on RT-THREAD

Teach you how to operate first, I just sorted it out recently and found the doxygen on RT-THREAD

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

Cannot generate documentation, some paths have changed.So let me fix it for you.

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

Now you only need to download the latest code after 2022.8.4.

Download code and software

• First download the source code of rt-thread https://github.com/RT-Thread/rt-thread/, you can use the following command

git clone [email protected]:RT-Thread/rt-thread.git --depth=1

• Download doxygen software (readme.md in doxygen folder) https://doxygen.nl/index.html

Just download the step installation package doxygen-1.9.4-setup.exe

• Install doxygen, there is nothing to pay attention to when installing, just go to the next step.

Generate html document

We open the software we just installed Doxywizard

Open in the menu File to open the following file in RT-THREAD rt-thread/documentation/doxygen/Doxyfile

Then just run run directly, all the operations are done.

If you want to read Chinese, you can also choose Chinese according to the following settings

Open html document

Find the generated html folder and open the index.html file

Show effect

Next, we can see the renderings, and we can see some comments written by everyone under the src directory

The above is basically how to use RT-THREAD's doxygen.Is it simple and convenient?

The following is a brief introduction to how to write doxygen yourself.

How Doxygen is written

vscode plugin installation

Let's talk about how to write doxygen first.The traditional method is to write directly with a text editor, which I will not introduce here.Here we use a tool to help us write commonly used doxygen.Open vscode and install the plugin doxygen

This plugin has two operations

• Enter ·/** at the head of the source code file, and then press the Enter key directly, you can see the automatically generated comments.

• Enter /** above the written function, and then press the Enter key, and you will see the effect.

doxygen file generation

Just open the Doxygen tool, select the source folder, and click run

doxygen configuration

Doxygen actually has a lot of configurations, here I will cite a few commonly used configurations.

The following configuration can generate a tree diagram on the left for easy viewing.Other configurations are not introduced one by one.

If you want to know more, please refer to the link

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

Some suggestions when doxygen writes

Question 1: Are doxygen's function comments written in header files or source files?

This is due to different company roles.If your code is as lib..c is not open to customers. At this time, it is better to write it in .h.

If you are doing open source, the source files can be released. At this time, it is better to put them in .c.In short, just put it in one place, and other places do not need to be written according to doxygen.

If you have any other questions, you can leave a message in the comment area and I will answer them one by one