4
0
mirror of https://github.com/RT-Thread/rt-thread.git synced 2025-02-22 03:55:24 +08:00

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 <unicorn_wang@outlook.com>
This commit is contained in:
Chen Wang 2025-02-13 23:28:19 +08:00 committed by GitHub
parent d8079e3843
commit f6f7d91a61
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
43 changed files with 123 additions and 123 deletions

View File

@ -1,8 +1,8 @@
@page howto_doxygen How to write doxygen documentation for RT-Thread
@page page_howto_doxygen How to write doxygen documentation for RT-Thread
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.
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.
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.
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.

View File

@ -1,4 +1,4 @@
@page introduction Introduction
@page page_introduction Introduction
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.

View File

@ -1,4 +1,4 @@
@page quickstart_keil Keil MDK Installation
@page page_quickstart_keil Keil MDK Installation
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.

View File

@ -1,4 +1,4 @@
@page quick_start Start Guide
@page page_quick_start Start Guide
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.
@ -10,7 +10,7 @@ What will follow is a demonstration of RT-Thread running on a simulated STM32F10
# Preparation
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.
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.
# First acquaintance with RT-Thread

View File

@ -1,10 +1,10 @@
@page kernel Kenrel
@page page_kernel Kenrel
- @subpage kernel_basics
- @subpage thread_management
- @subpage clock_management
- @subpage thread_sync
- @subpage thread_comm
- @subpage memory_management
- @subpage interrupt_management
- @subpage kernel_porting
- @subpage page_kernel_basics
- @subpage page_thread_management
- @subpage page_clock_management
- @subpage page_thread_sync
- @subpage page_thread_comm
- @subpage page_memory_management
- @subpage page_interrupt_management
- @subpage page_kernel_porting

View File

@ -1,5 +1,5 @@
@page tool Tool
@page page_tool Tool
- @subpage env
- @subpage page_env
- @subpage scons
- @subpage page_scons

View File

@ -1,14 +1,14 @@
@page device Device
@page page_device Device
- @subpage device_framework
- @subpage device_pin
- @subpage device_uart
- @subpage device_adc
- @subpage device_i2c
- @subpage device_spi
- @subpage device_pwm
- @subpage device_rtc
- @subpage device_hwtimer
- @subpage device_watchdog
- @subpage device_wlan
- @subpage device_sensor
- @subpage page_device_framework
- @subpage page_device_pin
- @subpage page_device_uart
- @subpage page_device_adc
- @subpage page_device_i2c
- @subpage page_device_spi
- @subpage page_device_pwm
- @subpage page_device_rtc
- @subpage page_device_hwtimer
- @subpage page_device_watchdog
- @subpage page_device_wlan
- @subpage page_device_sensor

View File

@ -1,12 +1,12 @@
@page components Components
@page page_components Components
- @subpage component_finsh
- @subpage component_vfs
- @subpage component_utest
- @subpage component_dlmodule
- @subpage component_sal
- @subpage component_at
- @subpage component_posix
- @subpage component_ulog
- @subpage component_pm
- @subpage component_network
- @subpage page_component_finsh
- @subpage page_component_vfs
- @subpage page_component_utest
- @subpage page_component_dlmodule
- @subpage page_component_sal
- @subpage page_component_at
- @subpage page_component_posix
- @subpage page_component_ulog
- @subpage page_component_pm
- @subpage page_component_network

View File

@ -1,4 +1,4 @@
@page code_contribution Contribution
@page page_code_contribution Contribution
# Contribution Guide
@ -6,6 +6,6 @@ We sincerely thank you for your contribution, and welcome to submit the code thr
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.
@subpage rtt_code_style_en
@subpage page_rtt_code_style_en
@subpage howto_doxygen
@subpage page_howto_doxygen

View File

@ -1,52 +1,52 @@
@mainpage RT-Thread User Guide
@subpage introduction
@subpage page_introduction
@subpage quick_start
@subpage page_quick_start
@subpage kernel
@subpage page_kernel
- @ref kernel_basics
- @ref thread_management
- @ref clock_management
- @ref thread_sync
- @ref thread_comm
- @ref memory_management
- @ref interrupt_management
- @ref kernel_porting
- @ref page_kernel_basics
- @ref page_thread_management
- @ref page_clock_management
- @ref page_thread_sync
- @ref page_thread_comm
- @ref page_memory_management
- @ref page_interrupt_management
- @ref page_kernel_porting
@subpage tool
@subpage page_tool
- @ref env
- @ref scons
- @ref page_env
- @ref page_scons
@subpage device
@subpage page_device
- @ref device_framework
- @ref device_pin
- @ref device_uart
- @ref device_adc
- @ref device_i2c
- @ref device_spi
- @ref device_pwm
- @ref device_rtc
- @ref device_hwtimer
- @ref device_watchdog
- @ref device_wlan
- @ref device_sensor
- @ref page_device_framework
- @ref page_device_pin
- @ref page_device_uart
- @ref page_device_adc
- @ref page_device_i2c
- @ref page_device_spi
- @ref page_device_pwm
- @ref page_device_rtc
- @ref page_device_hwtimer
- @ref page_device_watchdog
- @ref page_device_wlan
- @ref page_device_sensor
@subpage components
@subpage page_components
- @ref component_finsh
- @ref component_vfs
- @ref component_utest
- @ref component_dlmodule
- @ref component_sal
- @ref component_at
- @ref component_posix
- @ref component_ulog
- @ref component_pm
- @ref component_network
- @ref page_component_finsh
- @ref page_component_vfs
- @ref page_component_utest
- @ref page_component_dlmodule
- @ref page_component_sal
- @ref page_component_at
- @ref page_component_posix
- @ref page_component_ulog
- @ref page_component_pm
- @ref page_component_network
@subpage code_contribution
@subpage page_code_contribution

View File

@ -1,4 +1,4 @@
@page component_at AT Commands
@page page_component_at AT Commands
# Introduction to AT Commands

View File

@ -1,4 +1,4 @@
@page kernel_basics Kernel Basics
@page page_kernel_basics Kernel Basics
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.
After understanding this chapter, readers will have an elementary understanding of the RT Thread kernel and will be able to answer questions such as -

View File

@ -1,4 +1,4 @@
@page rtt_code_style_en RT-Thread Coding Style
@page page_rtt_code_style_en RT-Thread Coding Style
This is an developing instruction for RT-Thread developers. As open source
software, RT-Thread is created by the cooperation of different people. This

View File

@ -1,4 +1,4 @@
@page device_adc ADC Device
@page page_device_adc ADC Device
# An Introduction to ADC

View File

@ -1,4 +1,4 @@
@page device_framework I/O Device Framework
@page page_device_framework I/O Device Framework
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.

View File

@ -1,4 +1,4 @@
@page device_hwtimer HWTIMER Device
@page page_device_hwtimer HWTIMER Device
# Introduction to the Timer

View File

@ -1,4 +1,4 @@
@page device_i2c I2C Bus Device
@page page_device_i2c I2C Bus Device
# Introduction of I2C

View File

@ -1,4 +1,4 @@
@page device_pin PIN Device
@page page_device_pin PIN Device
# Introduction of Pin

View File

@ -1,4 +1,4 @@
@page device_pwm PWM Device
@page page_device_pwm PWM Device
# Introduction to PWM

View File

@ -1,4 +1,4 @@
@page device_rtc RTC Device
@page page_device_rtc RTC Device
# Introduction of RTC

View File

@ -1,4 +1,4 @@
@page device_sensor Sensor Device
@page page_device_sensor Sensor Device
# Introduction

View File

@ -1,4 +1,4 @@
@page device_spi SPI Device
@page page_device_spi SPI Device
# Introduction to SPI

View File

@ -1,4 +1,4 @@
@page device_uart UART Device
@page page_device_uart UART Device
# UART Introduction

View File

@ -1,4 +1,4 @@
@page device_watchdog WATCHDOG Device
@page page_device_watchdog WATCHDOG Device
# An Introduction to WATCHDOG

View File

@ -1,4 +1,4 @@
@page device_wlan WLAN Device
@page page_device_wlan WLAN Device
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.

View File

@ -1,4 +1,4 @@
@page component_dlmodule Dynamic Module: dlmodule
@page page_component_dlmodule Dynamic Module: dlmodule
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`.
@ -295,7 +295,7 @@ This function closes the dynamic library pointed to by `handle` and unloads it
# FAQs
Please refer to @ref env for issues related to the Env tool.
Please refer to @ref page_env for issues related to the Env tool.
## Q: Dynamic modules cannot be run successfully according to the documentation.

View File

@ -1,4 +1,4 @@
@page env User Manual of Env
@page page_env User Manual of Env
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.
@ -82,7 +82,7 @@ scons --target=mdk4
scons --target=mdk5
```
For more scons tutorials, please refer to @ref scons.
For more scons tutorials, please refer to @ref page_scons.
## BSP configuration: menuconfig

View File

@ -1,4 +1,4 @@
@page component_vfs Virtual File System
@page page_component_vfs Virtual File System
In early days, the amount of data to be stored in embedded systems was relatively small and data types were relatively simple.
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.

View File

@ -1,4 +1,4 @@
@page component_finsh FinSH Console
@page page_component_finsh FinSH Console
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.

View File

@ -1,4 +1,4 @@
@page interrupt_management Interrupt Management
@page page_interrupt_management Interrupt Management
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.

View File

@ -1,8 +1,8 @@
@page kernel_porting Kernel Porting
@page page_kernel_porting Kernel Porting
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 .
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.
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.
# CPU Architecture Porting

View File

@ -1,4 +1,4 @@
@page memory_management Memory Management
@page page_memory_management Memory Management
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.

View File

@ -1,4 +1,4 @@
@page component_network Network Framework
@page page_component_network Network Framework
With the popularity of the Internet, people's lives are increasingly dependent on the application of the network. More and more products need to connect to the Internet, and device networking has become a trend. To achieve the connection between the device and the network, you need to follow the TCP/IP protocol, you can run the network protocol stack on the device to connect to the network, or you can use devices (chips with hardware network protocol stack interfaces) to connect to the Internet.

View File

@ -1,4 +1,4 @@
@page component_pm Power Management: PM
@page page_component_pm Power Management: PM
The purpose of low power management of embedded system is to reduce system energy consumption as much as possible to prolong the standby time of equipment on the premise of satisfying users'performance requirements. The contradiction between high performance and limited battery energy is most prominent in embedded systems. The combination of hardware low power design and software low power management has become an effective means to solve the contradiction. Nowadays, all kinds of MCUs provide management interfaces in low power consumption more or less. For example, adjusting the frequency of the main control clock, changing the working voltage, adjusting or even closing the bus frequency, closing the working clock of peripheral equipment, etc. With the support of hardware, reasonable software design becomes the key to energy saving. Generally, low power management can be divided into three categories:

View File

@ -1,4 +1,4 @@
@page component_posix POSIX Interface
@page page_component_posix POSIX Interface
# Introduction to Pthreads
@ -55,7 +55,7 @@ RT-Thread implements most of the functions and constants of Pthreads, defined in
typedef rt_thread_t pthread_t;
```
`Pthread_t` is a redefinition of the `rt_thread_t` type, defined in the `pthread.h` header file. rt_thread_t is the thread handle (or thread identifier) of the RT-Thread and is a pointer to the thread control block. You need to define a variable of type pthread_t before creating a thread. Each thread corresponds to its own thread control block, which is a data structure used by the operating system to control threads. It stores some information about the thread, such as priority, thread name, and thread stack address. Thread control blocks and thread specific information are described in detail in the @ref thread_management chapter.
`Pthread_t` is a redefinition of the `rt_thread_t` type, defined in the `pthread.h` header file. rt_thread_t is the thread handle (or thread identifier) of the RT-Thread and is a pointer to the thread control block. You need to define a variable of type pthread_t before creating a thread. Each thread corresponds to its own thread control block, which is a data structure used by the operating system to control threads. It stores some information about the thread, such as priority, thread name, and thread stack address. Thread control blocks and thread specific information are described in detail in the @ref page_thread_management chapter.
## Create Thread
@ -436,7 +436,7 @@ The main APIs of the mutex include: calling `pthread_mutex_init()` to initialize
The rt-thread operating system implements a priority inheritance algorithm to prevent priority inversion.Priority inheritance is the practice of raising the priority of a low-priority thread that occupies a resource to the same level as the highest-priority thread of all the threads waiting for the resource, then executing, and then returning to the initial setting when the low-priority thread releases the resource.Thus, threads that inherit priority prevent system resources from being preempted by any intermediate priority thread.
For a detailed introduction to priority reversal, please refer to the @ref thread_sync Mutex section.
For a detailed introduction to priority reversal, please refer to the @ref page_thread_sync Mutex section.
## Mutex Lock Control Block

View File

@ -1,4 +1,4 @@
@page component_sal Socket Abstraction Layer: SAL
@page page_component_sal Socket Abstraction Layer: SAL
# SAL Introduction

View File

@ -1,4 +1,4 @@
@page scons SCons
@page page_scons SCons
# Introduction to SCons
@ -460,7 +460,7 @@ After saving the configuration, exit the configuration interface and open the rt
Because the RT_USING_HELLO macro has been defined in rtconfig.h, the source file for hello.c is added to the new project when the project is newly built.
The above simply enumerates the configuration options for adding your own modules to the Kconfig file. Users can also refer to @ref env, which also explains how to modify and add configuration options. They can also view the Kconfig documentation in your own Baidu to implement other more complex configuration options.
The above simply enumerates the configuration options for adding your own modules to the Kconfig file. Users can also refer to @ref page_env, which also explains how to modify and add configuration options. They can also view the Kconfig documentation in your own Baidu to implement other more complex configuration options.
## Add Library

View File

@ -1,4 +1,4 @@
@page thread_comm Inter-thread Communication
@page page_thread_comm Inter-thread Communication
In the last chapter, we talked about inter-thread synchronization, concepts such as semaphores, mutexes, and event sets were mentioned. Following the last chapter, this chapter is going to explain inter-thread communication. In bare-metal programming, global variables are often used for communication between functions. For example, some functions may change the value of a global variable due to some operations. Another function reads the global variable and will perform corresponding actions to achieve communication and collaboration according to the global variable values it read. More tools are available in RT-Thread to help pass information between different threads. These tools are covered in more detail in this chapter. After reading this chapter, you will learn how to use mailboxes, message queues, and signals for communication between threads.

View File

@ -1,4 +1,4 @@
@page thread_sync Inter-thread Synchronization
@page page_thread_sync Inter-thread Synchronization
In a multi-threaded real-time system, the completion of a task can often be accomplished through coordination of multiple threads, so how do these multiple threads collaborate well with each other to perform without errors? Here is an example.

View File

@ -1,4 +1,4 @@
@page thread_management Thread Management
@page page_thread_management Thread Management
When we are facing a big task in our daily life, we usually break it down into a number of simple, easy-to-manage smaller tasks. Then, we would deal with these smaller tasks one by one, gradually, the big task is worked out. In a multi-threaded operating system, developers also need to break down a complex application into multiple small, schedulable, and serialized program units. When tasks are reasonably divided and properly executed, this design allows the system to meet the capacity and time requirements of the real-time system. For example, to have the embedded system to perform such tasks, the system would collect data through sensors and display the data on the screen. In a multi-threaded real-time system, the task can be decomposed into two subtasks. The subtask, as shown in the following figure, reads the sensor data continuously and writes the data into the shared memory. The other subtask periodically reads the data from the shared memory and outputs the sensor data onto the screen.

View File

@ -1,4 +1,4 @@
@page clock_management Clock & Timer Management
@page page_clock_management Clock & Timer Management
The concept of time is very important. You need to set a time to go out with friends and it takes time to complete tasks. Life is inseparable from time. The same is true for operating systems, which require time to regulate the execution of their tasks. The smallest time unit in operating system is clock tick (OS Tick). This chapter focuses on introduction of clock ticks and clock-based timers. After reading this chapter, we will learn how clock ticks are generated and how to use RT-Thread timers.

View File

@ -1,4 +1,4 @@
@page component_ulog Ulog Log
@page page_component_ulog Ulog Log
# Ulog Introduction

View File

@ -1,4 +1,4 @@
@page component_utest utest Framework
@page page_component_utest utest Framework
# utest Introduction