embedded-docs

What this skill does

# 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:

```c
/**
 * @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:

```c
/**
 * @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:

```c
/**
 * @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:

```c
/**
 * @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:

```c
/**
 * @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

```bash
# 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 file