Code documentation Skill

Read docs_llm/LLM_GUIDE.md first. Document only the public API in the given header; never change code.

Inputs

• Header file path: the C/C++ header to document, normally under inc/<layer>/<module>/.

Steps

1. Read the header. List the public functions, types, enums, structs and macros.

2. Research the header before writing anything. The layout mirrors inc/, so for inc/<layer>/<module>/ez_x.h look at:

   • Implementation: src/<layer>/<module>/ez_x.c (or .cpp). Use Glob/Grep if the name differs. For each public function read the whole body and follow the helpers it calls.
   • Dependencies: every header the file includes (ez_utilities_common.h for ezSTATUS, ez_queue.h, ez_linked_list.h, ez_osal.h, ...). Read the types, enum values and macros that appear in the public signatures, and the documentation of the functions it calls.
   • Usage (mandatory, read it before writing any @code, @pre, @retval): find the unit test and open it. Do not rely on the exact path: the test folder and file name often differ from the header (for example inc/service/data_model/ez_data_model.h is tested in tests/service/datamodel/unittest_ez_datamodel.cpp) and tests can be .c or .cpp. Locate it with Glob tests/**/*unittest*<module>* with and without underscores, or Grep -rl "<first function name>" tests/. The test shows expected inputs, error cases and call order.
   • Callers: Grep -rl "<function prefix>" src inc samples (for example ezDataModel_) and open the real callers outside the module itself, such as src/platform/, samples/. Base @code blocks on them. If no test or caller exists, say so in the report and do not write an @code block.
   • Related API: Grep the header for sibling functions (FromISR variants, Init/Deinit, Create/Reset) for @see and for ISR rules.
   • Config: the #if (EZ_... == 1U) guard of the module and any EZ_* macro that changes behaviour or limits. Collect these facts for each function before step 4:

   Fact	Where to find it
   Every return value and what causes it	return statements, error paths, called functions' return values
   Preconditions	NULL and range checks, asserts, "must be initialized first" flags, required call order
   Postconditions and side effects	state written, events sent, queue contents changed, callbacks invoked
   Blocking	ezOsal_* waits, mutex/semaphore take, delays, loops with timeouts
   ISR safety	no blocking and no OS calls that are task-only; FromISR variant exists or is the variant
   Memory ownership	who owns buffers passed in, copy vs reference, lifetime of pointers (callback data, Init* buffers)
   Thread safety	locks taken, shared state touched
   Limits	buffer sizes, max listeners/items, units of time arguments

3. Keep existing comments that are correct. Rewrite the ones that are wrong or incomplete, and add the missing ones. Keep the wording and the author's intent where possible.

4. Write each comment using the formats below.

5. Build the docs with .claude/skills/code-document/scripts/run_doxygen.sh <header> and fix every warning reported for the header. Exit code 0 means no warnings, 1 means warnings, 2 means Doxygen is missing or failed; in that case say so in the report instead of retrying.

6. Mark anything you cannot confirm from the source as an open question in the report. Every @retval, @pre, @post, @isr_safe, @blocking and @warning must be backed by code you read. Never guess; leave the tag out and list it as an open question instead. Where the code and an existing comment disagree, trust the code and report the mismatch.

Format / conventions

Function

Use the banner style found in the existing headers. Parameters use name: description. @isr_safe{} and @blocking{} are Doxyfile aliases and render as ISR-safe: yes|no and Blocking: yes|no. Examples must check the return value and must not cast it to (void).

/*****************************************************************************
* Function : ezEventBus_CreateBus
*//** 
* @brief This function creates an event bus
*
* @details The user is RECOMMENDED to use this function to create the bus
* instead of modifying the struct directly.
*
* @param[in]    event_bus: Pointer to the event bus
* @param[in]    buff: Memory buffer given to the event bus to work with
* @param[in]    buff_size: Size of the memory buffer in bytes
* @return       ezSTATUS
*
* @retval ezSUCCESS             Bus created
* @retval ezSTATUS_ARG_INVALID  Pointer is NULL or buffer is too small
*
* @pre None
* @post None
* @warning Do not call from a listener callback.
* @isr_safe{no}
* @blocking{no}
* @see ezEventBus_ResetBus
*
* \b Example
* @code
* ezEventBus_t bus;
* uint8_t buffer[128];
* if (ezEventBus_CreateBus(&bus, buffer, sizeof(buffer)) != ezSUCCESS)
* {
*     HandleError();
* }
* @endcode
*
*****************************************************************************/
ezSTATUS ezEventBus_CreateBus(
    ezEventBus_t *event_bus,
    uint8_t *buff,
    uint32_t buff_size);

Omit @retval, @warning and @see when they do not apply. For void functions omit @return entirely: Doxygen warns on @return None.

File header

Keep the existing license banner untouched. Put the @file block directly after it.

/** @file   ez_event_bus.h
 *  @author Hai Nguyen
 *  @date   27.02.2024
 *  @brief  Public API of the event bus component.
 *
 *  @details Static storage only. No dynamic allocation.
 */

Types and macros

Single-line @brief for the type, /**< ... */ for members and enumerators.

/** @brief Status codes returned by the framework functions. */
typedef enum
{
    ezSUCCESS = 0,              /**< operation success */
    ezFAIL = -1,                /**< operation fail */
    ezSTATUS_ARG_INVALID = -2,  /**< invalid argument */
} ezSTATUS;

Rules

• Do not invent APIs, behaviour or tags. If it is not in the header or the source, do not write it.
• Do not change code. Edit or create Doxygen comments only.
• Do not touch the license banner, the include guards, the extern "C" block or the #if (EZ_... == 1U) guards.
• Document only the public API in the header. Do not document static or internal functions in source files.

Output

• Files changed or created.
• What was documented: functions, types and macros, grouped per file.
• Skipped symbols and open questions, with the reason for each.