Embedded Docs

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:

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 process
• hw-sw-interface-specification.js - Interface specification process
• AG-012: Technical Documentation Agent