---
id: TASK-3
title: Improve inline code annotations and execution docs
status: Done
assignee: []
created_date: '2026-01-29 18:34'
updated_date: '2026-01-29 18:50'
labels: []
dependencies: []
references:
  - lua/zync/api.lua
  - lua/zync/api/configurator.lua
  - lua/zync/api/manager.lua
  - lua/zync/api/commands/commands.lua
  - lua/zync/api/commands/Command.lua
  - lua/zync/lib/utils.lua
  - spec
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Bring inline documentation (LuaDoc-style annotations and explanatory comments) up to date across the zync codebase, focusing on critical execution flow and newly added features (profiles, logging, build dirs) so that API and runtime behavior are clearly described in code.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Inline docs/annotations are consistent and complete in core modules (api, configurator, manager, commands)
- [x] #2 Newly added functions (e.g., profile logging and profile selection) are documented with LuaDoc-style annotations and clear comments where needed
- [x] #3 Critical execution paths (command dispatch, config load, build dir resolution) have concise explanatory comments where previously sparse
- [x] #4 Doc updates avoid noisy or redundant comments and match existing style/formatting
- [x] #5 No behavior changes; only documentation/comment updates
- [x] #6 `busted` passes (or rationale noted if not run)
<!-- AC:END -->

## Final Summary

<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Refreshed inline LuaDoc across core modules with consistent blank-line formatting: `api.lua` now documents arg parsing, dispatch flow, and profile logging; `configurator.lua` covers profile selection/order and build/project dir resolution; `manager.lua` clarifies build dir helpers, sysbuild image flow, and command execution; commands module and utils have updated annotations (including `profiles` and log suppression). Documentation-only changes; no behavior modified.
<!-- SECTION:FINAL_SUMMARY:END -->
