majiayu000 Embedded Documentation Skill
Expert skill for embedded firmware documentation generation and maintenance. Provides Doxygen comment generation, API documentation structure, hardware interface documentation, and integration with documentation systems.
Overview
The Embedded Documentation skill enables comprehensive documentation for embedded firmware projects:
- Doxygen comment generation and maintenance
- API documentation structure and organization
- Hardware interface documentation
- Memory map documentation
- Call graph and dependency visualization
- Version changelog management
- Register documentation formatting
- Integration with Sphinx/MkDocs
Capabilities
1. Doxygen Comment Generation
Generate Doxygen-compatible documentation comments:
/**
* @file uart_driver.h
* @brief UART peripheral driver for STM32F4 series
* @author Firmware Team
* @version 1.2.0
* @date 2026-01-24
*
* @details
* This driver provides a hardware abstraction layer for UART peripherals.
* It supports:
* - Polling, interrupt, and DMA transfer modes
* - Hardware flow control (RTS/CTS)
* - Configurable baud rates up to 10.5 Mbps
* - Error detection and handling
*
* @note Thread-safe when used with RTOS mutual exclusion
*
* @par Example Usage:
* @code
* uart_config_t config = {
* .baudrate = 115200,
* .parity = UART_PARITY_NONE,
* .stop_bits = UART_STOP_1
* };
* uart_init(UART1, &config);
* uart_transmit(UART1, data, len, 100);
* @endcode
*
* @copyright (c) 2026 Company Name. All rights reserved.
*/
2. Function Documentation
Document functions with complete parameter and return information:
/**
* @brief Initialize UART peripheral with specified configuration
*
* Configures the UART hardware with the specified settings and prepares
* it for data transmission and reception. Must be called before any
* other UART operations.
*
* @param[in] uart UART peripheral instance (UART1, UART2, etc.)
* @param[in] config Pointer to configuration structure
*
* @return Status code indicating success or failure
* @retval UART_OK Initialization successful
* @retval UART_ERR_INVALID Invalid parameter (NULL pointer or invalid instance)
* @retval UART_ERR_BUSY Peripheral is busy or already initialized
* @retval UART_ERR_CLOCK Clock configuration failed
*
* @pre System clocks must be configured before calling this function
* @post UART peripheral is ready for data transfer
*
* @note This function enables the peripheral clock automatically
* @warning Do not call from interrupt context
*
* @see uart_deinit()
* @see uart_config_t
*
* @par Thread Safety:
* This function is NOT thread-safe. Use mutex protection when
* calling from multiple threads.
*
* @par Example:
* @code
* uart_status_t status = uart_init(UART1, &config);
* if (status != UART_OK) {
* handle_error(status);
* }
* @endcode
*/
uart_status_t uart_init(uart_instance_t uart, const uart_config_t *config);
3. Hardware Register Documentation
Document hardware register definitions:
/**
* @defgroup UART_Registers UART Register Definitions
* @brief Memory-mapped register definitions for UART peripheral
* @{
*/
/**
* @brief UART Control Register 1 (CR1)
*
* @verbatim
* Bit Field | Name | R/W | Reset | Description
* ------------|---------|-----|-------|---------------------------
* [31:16] | - | - | 0 | Reserved
* [15] | OVER8 | RW | 0 | Oversampling mode (0=16x, 1=8x)
* [14] | - | - | 0 | Reserved
* [13] | UE | RW | 0 | UART enable
* [12] | M | RW | 0 | Word length (0=8bit, 1=9bit)
* [11] | WAKE | RW | 0 | Wakeup method
* [10] | PCE | RW | 0 | Parity control enable
* [9] | PS | RW | 0 | Parity selection (0=even, 1=odd)
* [8] | PEIE | RW | 0 | PE interrupt enable
* [7] | TXEIE | RW | 0 | TXE interrupt enable
* [6] | TCIE | RW | 0 | TC interrupt enable
* [5] | RXNEIE | RW | 0 | RXNE interrupt enable
* [4] | IDLEIE | RW | 0 | IDLE interrupt enable
* [3] | TE | RW | 0 | Transmitter enable
* [2] | RE | RW | 0 | Receiver enable
* [1] | RWU | RW | 0 | Receiver wakeup
* [0] | SBK | RW | 0 | Send break
* @endverbatim
*/
#define UART_CR1_OVER8_Pos (15U)
#define UART_CR1_OVER8_Msk (0x1UL << UART_CR1_OVER8_Pos)
#define UART_CR1_OVER8 UART_CR1_OVER8_Msk
/** @} */ /* End of UART_Registers group */
4. Memory Map Documentation
Document memory layout and regions:
/**
* @defgroup Memory_Map Memory Map
* @brief System memory map documentation
*
* @verbatim
* Memory Map Overview (STM32F407VG)
* =================================
*
* Address Range | Size | Region | Description
* -----------------------|---------|-----------------|------------------
* 0x00000000-0x07FFFFFF | 128 MB | Aliased | Boot memory alias
* 0x08000000-0x080FFFFF | 1 MB | Flash | Main flash memory
* 0x10000000-0x1000FFFF | 64 KB | CCMRAM | Core-coupled RAM
* 0x1FFF0000-0x1FFF7A0F | 30 KB | System Memory | Bootloader ROM
* 0x1FFFC000-0x1FFFC007 | 8 B | OTP | Option bytes
* 0x20000000-0x2001FFFF | 128 KB | SRAM | Main SRAM
* 0x40000000-0x400FFFFF | 1 MB | APB1 | APB1 peripherals
* 0x40010000-0x4001FFFF | 64 KB | APB2 | APB2 peripherals
* 0x40020000-0x4007FFFF | 384 KB | AHB1 | AHB1 peripherals
* 0x50000000-0x5003FFFF | 256 KB | AHB2 | AHB2 peripherals
* 0xE0000000-0xE00FFFFF | 1 MB | Cortex-M4 | System control
*
* Flash Memory Layout
* ===================
*
* Sector | Address | Size | Usage
* -------|-------------|--------|------------------
* 0 | 0x08000000 | 16 KB | Bootloader
* 1 | 0x08004000 | 16 KB | Bootloader
* 2 | 0x08008000 | 16 KB | Application (start)
* 3 | 0x0800C000 | 16 KB | Application
* 4 | 0x08010000 | 64 KB | Application
* 5-11 | 0x08020000 | 896 KB | Application/Data
*
* @endverbatim
*/
5. API Documentation Structure
Organize documentation with module grouping:
/**
* @mainpage Firmware API Reference
*
* @section intro Introduction
* This documentation describes the firmware API for the XYZ product.
*
* @section modules Module Overview
* - @ref HAL_Module "Hardware Abstraction Layer"
* - @ref Driver_Module "Device Drivers"
* - @ref App_Module "Application Layer"
* - @ref Utils_Module "Utility Functions"
*
* @section getting_started Getting Started
* See @ref quick_start for initialization examples.
*
* @section architecture Architecture
* @image html architecture.png "Firmware Architecture"
*/
/**
* @defgroup HAL_Module Hardware Abstraction Layer
* @brief Low-level hardware interface modules
* @{
*/
/**
* @defgroup HAL_GPIO GPIO Driver
* @brief General Purpose Input/Output driver
*/
/**
* @defgroup HAL_UART UART Driver
* @brief Universal Asynchronous Receiver/Transmitter driver
*/
/** @} */ /* End of HAL_Module */
Process Integration
This skill integrates with the following processes:
| Process | Integration Point |
|---|---|
firmware-api-documentation.js |
Primary documentation generation |
hw-sw-interface-specification.js |
Interface documentation |
version-control-config-management.js |
Release documentation |
Workflow
1. Analyze Codebase
# Find undocumented functions
grep -rn "^[a-z_]*\s\+[a-z_]*(" src/ | grep -v "/\*\*"
# Count documented vs undocumented
find src/ -name "*.h" -exec grep -l "@brief" {} \; | wc -l
find src/ -name "*.h" | wc -l
2. Generate Documentation Comments
The skill generates documentation comments for:
- Header files (module overview, includes, defines)
- Function declarations (params, returns, examples)
- Data structures (fields, usage)
- Enumerations (values, descriptions)
- Macros (purpose, usage)
3. Configure Doxygen
# Doxyfile configuration highlights
PROJECT_NAME = "Firmware API"
PROJECT_NUMBER = 1.2.0
OUTPUT_DIRECTORY = docs/api
GENERATE_HTML = YES
GENERATE_LATEX = NO
EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = YES
INPUT = src include
FILE_PATTERNS = *.c *.h
RECURSIVE = YES
EXCLUDE = src/third_party
HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
4. Generate Output
# Generate HTML documentation
doxygen Doxyfile
# Generate PDF (requires LaTeX)
cd docs/api/latex && make pdf
# Serve locally for review
python -m http.server 8000 -d docs/api/html
Output Schema
{
"documentation": {
"type": "doxygen",
"format": "html",
"outputDir": "docs/api"
},
"coverage": {
"files": {
"total": 45,
"documented": 42,
"coverage": 0.933
},
"functions": {
"total": 156,
"documented": 148,
"coverage": 0.949
},
"parameters": {
"total": 312,
"documented": 298,
"coverage": 0.955
}
},
"warnings": [
"src/legacy.c:45: Missing @return documentation",
"include/config.h:12: Undocumented macro CONFIG_MAX_SIZE"
],
"artifacts": [
"docs/api/html/index.html",
"docs/api/Doxyfile",
"docs/memory-map.md",
"docs/register-reference.md"
]
}
Documentation Templates
Header File Template
/**
* @file module_name.h
* @brief Brief module description
* @author Author Name
* @version X.Y.Z
* @date YYYY-MM-DD
*
* @details
* Detailed description of the module purpose and functionality.
*
* @par Dependencies:
* - dependency1.h
* - dependency2.h
*
* @par Example:
* @code
* // Usage example
* @endcode
*/
#ifndef MODULE_NAME_H
#define MODULE_NAME_H
#ifdef __cplusplus
extern "C" {
#endif
/* Includes */
/* Defines */
/* Types */
/* Function Prototypes */
#ifdef __cplusplus
}
#endif
#endif /* MODULE_NAME_H */
Driver Function Template
/**
* @brief Brief description (imperative mood)
*
* Detailed description explaining what the function does,
* when to use it, and any important considerations.
*
* @param[in] param1 Description of input parameter
* @param[out] param2 Description of output parameter
* @param[in,out] param3 Description of input/output parameter
*
* @return Description of return value
* @retval VALUE1 Meaning of VALUE1
* @retval VALUE2 Meaning of VALUE2
*
* @pre Preconditions that must be met
* @post Postconditions after successful execution
*
* @note Additional notes for users
* @warning Warnings about potential issues
*
* @see Related functions or documentation
*/
Best Practices
Comment Style
- Use brief descriptions starting with verb (Initialize, Configure, Get)
- Document all public API functions completely
- Include @param for every parameter
- Include @return and @retval for return values
- Add @pre/@post for state requirements
Organization
- Group related functions with @defgroup
- Use @ingroup to add items to groups
- Create a @mainpage for navigation
- Link related items with @see and @ref
Maintenance
- Update version numbers in @version tags
- Keep @date current with last modification
- Review and update documentation during code review
- Run Doxygen in CI to catch warnings
Integration with Documentation Systems
Sphinx Integration
.. doxygenfile:: uart_driver.h
:project: firmware
.. doxygenfunction:: uart_init
:project: firmware
MkDocs Integration
# mkdocs.yml
plugins:
- mkdoxy:
projects:
firmware:
src-dirs: src include
full-doc: True
References
- Doxygen Manual: https://www.doxygen.nl/manual/
- MISRA C Documentation Guidelines
- Embedded Artistry Documentation Standards
- Linux Kernel Documentation Guidelines
See Also
firmware-api-documentation.js- Documentation generation processhw-sw-interface-specification.js- Interface specification process- AG-012: Technical Documentation Agent