Embedded firmware documentation generation and maintenance using Doxygen and related tools. Expert skill for API documentation, hardware interface documentation, memory maps, and integration with documentation systems.
Generates and maintains embedded firmware documentation using Doxygen for APIs, hardware interfaces, and memory maps.
npx claudepluginhub a5c-ai/babysitterThis skill is limited to using the following tools:
README.mdExpert skill for embedded firmware documentation generation and maintenance. Provides Doxygen comment generation, API documentation structure, hardware interface documentation, and integration with documentation systems.
The Embedded Documentation skill enables comprehensive documentation for embedded firmware projects:
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.
*/
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);
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 */
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
*/
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 */
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 |
# 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
The skill generates documentation comments for:
# 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
# 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
{
"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"
]
}
/**
* @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 */
/**
* @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
*/
.. doxygenfile:: uart_driver.h
:project: firmware
.. doxygenfunction:: uart_init
:project: firmware
# mkdocs.yml
plugins:
- mkdoxy:
projects:
firmware:
src-dirs: src include
full-doc: True
firmware-api-documentation.js - Documentation generation processhw-sw-interface-specification.js - Interface specification processActivates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.