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 -l2. Generate Documentation Comments
The skill generates documentation comments for:
- Header files