Skip to content

Commit f6f7d91

Browse files
authored
doxygen: add prefix for page name (#9989)
Add prefix "page_" to the name of pages. Add this as a rule in guide of writing doxygen documents. Signed-off-by: Chen Wang <[email protected]>
1 parent d8079e3 commit f6f7d91

File tree

43 files changed

+133
-133
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+133
-133
lines changed

documentation/0.doxygen/INDEX.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
@page howto_doxygen How to write doxygen documentation for RT-Thread
1+
@page page_howto_doxygen How to write doxygen documentation for RT-Thread
22

33
RT-Thread Online Documentation is created based on doxygen and is available at: <https://rt-thread.github.io/rt-thread/>. It is consisted of two parts.
44

5-
One part is the detailed introduction of Kernel, which is written in markdown format and converted into HTML page by doxygen. It is displayed under "RT-Thread User Guide" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's [subpage mechanism][2]. There are no special requirements for writing this part, so I will not go into details in this article.
5+
One part is the detailed introduction of Kernel, which is written in markdown format and converted into HTML page by doxygen. It is displayed under "RT-Thread User Guide" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's [subpage mechanism][2]. To define a page, we use `@page` command. The page name should be prefixed with a "page_", and the page name should be unique. Besides this, there are no special requirements for writing this part, so I will not go into details in this article.
66

77
The other part is the description of API. RT-Thread uses [doxygen][1] to automate the generation of documentation from source code comments, parsing information about classes, functions, and variables to produce output in format of HTML. It is displayed under "Modules" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's [topics mechanism][3]. The main content of this article is to describe how to write API with doxygen.
88

documentation/1.introduction/introduction.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page introduction Introduction
1+
@page page_introduction Introduction
22

33
As a beginner of Real-time Operating Systems (RTOS), you might be new to RT-Thread. However, with a better understanding of it over time, you will gradually discover the charm of RT-Thread and its advantages over other RTOSs of the same type. RT-Thread is an RTOS. With over 16 years of experience accumulated, along with the rise of the Internet of Things (IoT), it is evolving into a powerful, component-rich IoT operating system.
44

documentation/2.quick-start/keil-installation/keil-installation.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page quickstart_keil Keil MDK Installation
1+
@page page_quickstart_keil Keil MDK Installation
22

33
Before running the RT-Thread operating system, we need to install MDK-ARM 5.24 (either official or evaluation version, version 5.14 and above), this version is also a relatively new version. This version can provide relatively complete debugging functions. Here, we are using evaluation version 5.24 of 16k compiled code limit. If you want to remove the 16k compiled code limit, please purchase the official MDK-ARM.
44

documentation/2.quick-start/quick-start.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page quick_start Start Guide
1+
@page page_quick_start Start Guide
22

33
Because of its particularity, the embedded operating system is often closely related to the hardware platform, and specific embedded operating systems can only run on specific hardware. For those who might not have an RT-Thread compatible hardware module, or want to test out their ideas, a complete RT-Thread system can be developed in the simulation environment MDK-ARM.
44

@@ -10,7 +10,7 @@ What will follow is a demonstration of RT-Thread running on a simulated STM32F10
1010

1111
# Preparation
1212

13-
MDK development environment: MDK-ARM 5.24 (official or evaluation version, version 5.14 and above) needs to be installed. This version is a relatively new version, which can provide relatively complete debugging functions. An installation guide can be found here: @subpage quickstart_keil.
13+
MDK development environment: MDK-ARM 5.24 (official or evaluation version, version 5.14 and above) needs to be installed. This version is a relatively new version, which can provide relatively complete debugging functions. An installation guide can be found here: @subpage page_quickstart_keil.
1414

1515
# First acquaintance with RT-Thread
1616

documentation/3.kernel/INDEX.md

+9-9
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
@page kernel Kenrel
1+
@page page_kernel Kenrel
22

3-
- @subpage kernel_basics
4-
- @subpage thread_management
5-
- @subpage clock_management
6-
- @subpage thread_sync
7-
- @subpage thread_comm
8-
- @subpage memory_management
9-
- @subpage interrupt_management
10-
- @subpage kernel_porting
3+
- @subpage page_kernel_basics
4+
- @subpage page_thread_management
5+
- @subpage page_clock_management
6+
- @subpage page_thread_sync
7+
- @subpage page_thread_comm
8+
- @subpage page_memory_management
9+
- @subpage page_interrupt_management
10+
- @subpage page_kernel_porting

documentation/4.tool/INDEX.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
@page tool Tool
1+
@page page_tool Tool
22

3-
- @subpage env
3+
- @subpage page_env
44

5-
- @subpage scons
5+
- @subpage page_scons

documentation/5.device/INDEX.md

+13-13
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
@page device Device
1+
@page page_device Device
22

3-
- @subpage device_framework
4-
- @subpage device_pin
5-
- @subpage device_uart
6-
- @subpage device_adc
7-
- @subpage device_i2c
8-
- @subpage device_spi
9-
- @subpage device_pwm
10-
- @subpage device_rtc
11-
- @subpage device_hwtimer
12-
- @subpage device_watchdog
13-
- @subpage device_wlan
14-
- @subpage device_sensor
3+
- @subpage page_device_framework
4+
- @subpage page_device_pin
5+
- @subpage page_device_uart
6+
- @subpage page_device_adc
7+
- @subpage page_device_i2c
8+
- @subpage page_device_spi
9+
- @subpage page_device_pwm
10+
- @subpage page_device_rtc
11+
- @subpage page_device_hwtimer
12+
- @subpage page_device_watchdog
13+
- @subpage page_device_wlan
14+
- @subpage page_device_sensor

documentation/6.components/INDEX.md

+11-11
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
@page components Components
1+
@page page_components Components
22

3-
- @subpage component_finsh
4-
- @subpage component_vfs
5-
- @subpage component_utest
6-
- @subpage component_dlmodule
7-
- @subpage component_sal
8-
- @subpage component_at
9-
- @subpage component_posix
10-
- @subpage component_ulog
11-
- @subpage component_pm
12-
- @subpage component_network
3+
- @subpage page_component_finsh
4+
- @subpage page_component_vfs
5+
- @subpage page_component_utest
6+
- @subpage page_component_dlmodule
7+
- @subpage page_component_sal
8+
- @subpage page_component_at
9+
- @subpage page_component_posix
10+
- @subpage page_component_ulog
11+
- @subpage page_component_pm
12+
- @subpage page_component_network

documentation/7.contribution/INDEX.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
@page code_contribution Contribution
1+
@page page_code_contribution Contribution
22

33
# Contribution Guide
44

55
We sincerely thank you for your contribution, and welcome to submit the code through GitHub's fork and Pull Request processes. RT-Thread 3.1.0 version and its earlier versions follow the GPL V2 open source license agreement. Versions from the 3.1.0 version onwards follow the Apache License 2.0 open source license agreement.
66

77
All the real-time operating system kernel and open source components can be used free of charge for commercial products, there is no potential commercial risk and you will not being request to publish application source.
88

9-
@subpage rtt_code_style_en
9+
@subpage page_rtt_code_style_en
1010

11-
@subpage howto_doxygen
11+
@subpage page_howto_doxygen

documentation/INDEX.md

+49-49
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,52 @@
11
@mainpage RT-Thread User Guide
22

3-
@subpage introduction
4-
5-
@subpage quick_start
6-
7-
@subpage kernel
8-
9-
- @ref kernel_basics
10-
- @ref thread_management
11-
- @ref clock_management
12-
- @ref thread_sync
13-
- @ref thread_comm
14-
- @ref memory_management
15-
- @ref interrupt_management
16-
- @ref kernel_porting
17-
18-
@subpage tool
19-
20-
- @ref env
21-
- @ref scons
22-
23-
@subpage device
24-
25-
- @ref device_framework
26-
- @ref device_pin
27-
- @ref device_uart
28-
- @ref device_adc
29-
- @ref device_i2c
30-
- @ref device_spi
31-
- @ref device_pwm
32-
- @ref device_rtc
33-
- @ref device_hwtimer
34-
- @ref device_watchdog
35-
- @ref device_wlan
36-
- @ref device_sensor
37-
38-
@subpage components
39-
40-
- @ref component_finsh
41-
- @ref component_vfs
42-
- @ref component_utest
43-
- @ref component_dlmodule
44-
- @ref component_sal
45-
- @ref component_at
46-
- @ref component_posix
47-
- @ref component_ulog
48-
- @ref component_pm
49-
- @ref component_network
50-
51-
@subpage code_contribution
3+
@subpage page_introduction
4+
5+
@subpage page_quick_start
6+
7+
@subpage page_kernel
8+
9+
- @ref page_kernel_basics
10+
- @ref page_thread_management
11+
- @ref page_clock_management
12+
- @ref page_thread_sync
13+
- @ref page_thread_comm
14+
- @ref page_memory_management
15+
- @ref page_interrupt_management
16+
- @ref page_kernel_porting
17+
18+
@subpage page_tool
19+
20+
- @ref page_env
21+
- @ref page_scons
22+
23+
@subpage page_device
24+
25+
- @ref page_device_framework
26+
- @ref page_device_pin
27+
- @ref page_device_uart
28+
- @ref page_device_adc
29+
- @ref page_device_i2c
30+
- @ref page_device_spi
31+
- @ref page_device_pwm
32+
- @ref page_device_rtc
33+
- @ref page_device_hwtimer
34+
- @ref page_device_watchdog
35+
- @ref page_device_wlan
36+
- @ref page_device_sensor
37+
38+
@subpage page_components
39+
40+
- @ref page_component_finsh
41+
- @ref page_component_vfs
42+
- @ref page_component_utest
43+
- @ref page_component_dlmodule
44+
- @ref page_component_sal
45+
- @ref page_component_at
46+
- @ref page_component_posix
47+
- @ref page_component_ulog
48+
- @ref page_component_pm
49+
- @ref page_component_network
50+
51+
@subpage page_code_contribution
5252

documentation/at/at.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page component_at AT Commands
1+
@page page_component_at AT Commands
22

33
# Introduction to AT Commands
44

documentation/basic/basic.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page kernel_basics Kernel Basics
1+
@page page_kernel_basics Kernel Basics
22

33
This chapter gives a brief introduction to the software architecture of the RT-Thread kernel, beginning with its composition and implementation. While also introducing RT-Thread kernel-related concepts for beginners.
44
After understanding this chapter, readers will have an elementary understanding of the RT Thread kernel and will be able to answer questions such as -

documentation/contribution_guide/coding_style_en.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page rtt_code_style_en RT-Thread Coding Style
1+
@page page_rtt_code_style_en RT-Thread Coding Style
22

33
This is an developing instruction for RT-Thread developers. As open source
44
software, RT-Thread is created by the cooperation of different people. This

documentation/device/adc/adc.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_adc ADC Device
1+
@page page_device_adc ADC Device
22

33
# An Introduction to ADC
44

documentation/device/device.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_framework I/O Device Framework
1+
@page page_device_framework I/O Device Framework
22

33
Most embedded systems include some I/O (Input/Output) devices, data displays on instruments, serial communication on industrial devices, Flash or SD cards for saving data on data acquisition devices,as well as Ethernet interfaces for network devices, are examples of I/O devices that are commonly seen in embedded systems.
44

documentation/device/hwtimer/hwtimer.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_hwtimer HWTIMER Device
1+
@page page_device_hwtimer HWTIMER Device
22

33
# Introduction to the Timer
44

documentation/device/i2c/i2c.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_i2c I2C Bus Device
1+
@page page_device_i2c I2C Bus Device
22

33
# Introduction of I2C
44

documentation/device/pin/pin.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_pin PIN Device
1+
@page page_device_pin PIN Device
22

33
# Introduction of Pin
44

documentation/device/pwm/pwm.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_pwm PWM Device
1+
@page page_device_pwm PWM Device
22

33
# Introduction to PWM
44

documentation/device/rtc/rtc.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_rtc RTC Device
1+
@page page_device_rtc RTC Device
22

33
# Introduction of RTC
44

documentation/device/sensor/sensor.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_sensor Sensor Device
1+
@page page_device_sensor Sensor Device
22

33
# Introduction
44

documentation/device/spi/spi.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_spi SPI Device
1+
@page page_device_spi SPI Device
22

33
# Introduction to SPI
44

documentation/device/uart/uart.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_uart UART Device
1+
@page page_device_uart UART Device
22

33
# UART Introduction
44

documentation/device/watchdog/watchdog.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_watchdog WATCHDOG Device
1+
@page page_device_watchdog WATCHDOG Device
22

33
# An Introduction to WATCHDOG
44

documentation/device/wlan/wlan.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page device_wlan WLAN Device
1+
@page page_device_wlan WLAN Device
22

33
With the rapid development of the Internet of Things, more and more embedded devices are equipped with WIFI wireless network devices. In order to be able to manage WIFI network devices, RT-Thread introduces a WLAN device management framework. This framework has many features to control and manage WIFI, providing developers with many conveniences for using WIFI devices.
44

documentation/dlmodule/README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page component_dlmodule Dynamic Module: dlmodule
1+
@page page_component_dlmodule Dynamic Module: dlmodule
22

33
In traditional desktop operating systems, user space and kernel space are separate. The application runs in user space, and the kernel and kernel modules run in kernel space. The kernel module can be dynamically loaded and deleted to extend the kernel functionality. `dlmodule` is a software component of the dynamic module loading mechanism provided in kernel space of RT-Thread. In versions of RT-Thread v3.1.0, this was also called the `Application Module`. After RT-Thread v3.1.0 and later, it returned to the tradition and was named after the `dynamic module`.
44

@@ -295,7 +295,7 @@ This function closes the dynamic library pointed to by `handle` and unloads it
295295
296296
# FAQs
297297
298-
Please refer to @ref env for issues related to the Env tool.
298+
Please refer to @ref page_env for issues related to the Env tool.
299299
300300
## Q: Dynamic modules cannot be run successfully according to the documentation.
301301

documentation/env/env.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page env User Manual of Env
1+
@page page_env User Manual of Env
22

33
Env is a handy utility tool developed by RT-Thread team to build environment, graphical system configuration, and packages management for software projects that intend to run on RT-Thread operating system. Env tool come with source code builder, compilation environment and package management system.
44

@@ -82,7 +82,7 @@ scons --target=mdk4
8282
scons --target=mdk5
8383
```
8484

85-
For more scons tutorials, please refer to @ref scons.
85+
For more scons tutorials, please refer to @ref page_scons.
8686

8787
## BSP configuration: menuconfig
8888

documentation/filesystem/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page component_vfs Virtual File System
1+
@page page_component_vfs Virtual File System
22

33
In early days, the amount of data to be stored in embedded systems was relatively small and data types were relatively simple.
44
The data were stored by directly writing to a specific address in storage devices. However, with today modern technology, embedded device's functions are getting complicated and required more data storage. Therefore, we need new data management methods to simplify and organize the data storage.

documentation/finsh/finsh.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page component_finsh FinSH Console
1+
@page page_component_finsh FinSH Console
22

33
In the early days of computer development, before the advent of graphics systems, there was no mouse or even a keyboard. How did people interact with computers at the time? The earliest computers used a punched note to enter commands into the computer and write the program. Later, with the continuous development of computers, monitors and keyboards became the standard configuration of computers, but the operating system at this time did not support the graphical interface. Computer pioneers developed a software that accepts commands entered by the user, and after interpretation, passes it to The operating system and return the results of the operating system execution to the user. This program wraps around the operating system like a layer of shell, so it's called a shell.
44

documentation/interrupt/interrupt.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page interrupt_management Interrupt Management
1+
@page page_interrupt_management Interrupt Management
22

33
Interrupts often occur in embedded operating systems. When the CPU is processing a normal task, an external urgent event has occurred, requiring the CPU to suspend the current task to handle the asynchronous event. After the external event has been handled, CPU then returns to the interrupted address to continue working on the previous task. The system that implements this function is called the interrupt system, and the source of the request requesting for the CPU interrupt is called the interrupt source. An interrupt is an exception. An exception is any event that causes the processor to move away from normal operation and execute special code. If it is not processed in time, the system will either encounter an error or face a complete breakdown. So appropriately handling exceptions to avoid errors is a very important part of improving software robustness (stability). The following picture is a simple interrupt diagram.
44

documentation/kernel-porting/kernel-porting.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
@page kernel_porting Kernel Porting
1+
@page page_kernel_porting Kernel Porting
22

33
After learning the previous chapters, everyone has a better understanding of RT-Thread, but many people are not familiar with how to port the RT-Thread kernel to different hardware platforms. Kernel porting refers to the RT-Thread kernel running on different chip architectures and different boards. It can have functions such as thread management and scheduling, memory management, inter-thread synchronization and communication, and timer management. Porting can be divided into two parts: CPU architecture porting and BSP (Board support package) porting .
44

5-
This chapter will introduce CPU architecture porting and BSP porting. The CPU architecture porting part will be introduced in conjunction with the Cortex-M CPU architecture. Therefore, it is necessary to review "Cortex-M CPU Architecture Foundation" in the previous chapter @ref interrupt_management. After reading this chapter, how to complete the RT-Thread kernel porting will be learned.
5+
This chapter will introduce CPU architecture porting and BSP porting. The CPU architecture porting part will be introduced in conjunction with the Cortex-M CPU architecture. Therefore, it is necessary to review "Cortex-M CPU Architecture Foundation" in the previous chapter @ref page_interrupt_management. After reading this chapter, how to complete the RT-Thread kernel porting will be learned.
66

77
# CPU Architecture Porting
88

documentation/memory/memory.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@page memory_management Memory Management
1+
@page page_memory_management Memory Management
22

33
In a computing system, there are usually two types of memory space: internal memory space and external memory space. Internal memory can be quickly accessed, its contents can be read to and changed and only an address is required. The contents of internal memory are deleted after each power off. It is what would usually be called RAM (Random Access Memory) and is analogous to the RAM in a desktop computer. On the other hand, external memory has relatively fixed contents, retains data even after power off. It is usually called ROM (Read-Only Memory) and is analogous to the hard disk in a desktop computer.
44

0 commit comments

Comments
 (0)