KofTwentyTwo/Jarvis
2
0 Fork 0
Code Issues 111 Pull Requests 16 Actions Packages Projects Releases 4 Wiki Activity

P2: Apply commenting style guide to Voice package load-bearing actors #70

New Issue
Open
opened 2026-05-12 19:21:27 +00:00 by KofTwentyTwo · 0 comments
KofTwentyTwo commented 2026-05-12 19:21:27 +00:00 (Migrated from github.com)
Copy link
Copy source

Goal

Bring the Voice package's load-bearing actors up to the standard in .planning/code-commenting-guide.md.

Files in scope

  • packages/Voice/Sources/Voice/AudioGraphOwner.swift
  • packages/Voice/Sources/Voice/VoiceController.swift
  • packages/Voice/Sources/Voice/TTSEngineActor.swift
  • packages/Voice/Sources/Voice/BufferBroadcaster.swift

Constraints

  • ONE atomic commit per file (4 commits total). No code behavior changes — comments + docstrings only.
  • 18/18 boundary gates green.
  • Apply the guide's 5 comment shapes per file:
    • 5-line opener (WHY this actor exists, threading model, who calls it)
    • Type-level /// docstring with Overview + Topics + Threading + See Also
    • Method-level docstrings on public + key private methods
    • ASCII diagram where the file owns an orchestration or state machine (e.g., voice state transitions in VoiceController; serial-executor command-buffer rationale in TTSEngineActor)
    • "Before you edit" invariants block (e.g., no null voice adapters; presence-bus vs TTS-orchestrator boundary; single-writer for HUD voice state; AudioGraph format contract; broadcaster fan-out rules)
    • MARK dividers as a table of contents

Anti-patterns to remove

  • Plan-ID-only comments — rewrite WHY-first.
  • Stale references to closed Plan IDs or removed types.
  • Bare TODO: / FIXME: without issue link.

Follow the canonical pattern

Use the AppDelegate.swift P0 rewrite (#65) as the canonical applied pattern.

Parent epic

#64

Source

.planning/code-commenting-guide.md → Migration plan → P2

## Goal Bring the Voice package's load-bearing actors up to the standard in `.planning/code-commenting-guide.md`. ## Files in scope - `packages/Voice/Sources/Voice/AudioGraphOwner.swift` - `packages/Voice/Sources/Voice/VoiceController.swift` - `packages/Voice/Sources/Voice/TTSEngineActor.swift` - `packages/Voice/Sources/Voice/BufferBroadcaster.swift` ## Constraints - ONE atomic commit per file (4 commits total). No code behavior changes — comments + docstrings only. - 18/18 boundary gates green. - Apply the guide's 5 comment shapes per file: - 5-line opener (WHY this actor exists, threading model, who calls it) - Type-level `///` docstring with Overview + Topics + Threading + See Also - Method-level docstrings on public + key private methods - ASCII diagram where the file owns an orchestration or state machine (e.g., voice state transitions in VoiceController; serial-executor command-buffer rationale in TTSEngineActor) - "Before you edit" invariants block (e.g., no null voice adapters; presence-bus vs TTS-orchestrator boundary; single-writer for HUD voice state; AudioGraph format contract; broadcaster fan-out rules) - MARK dividers as a table of contents ## Anti-patterns to remove - Plan-ID-only comments — rewrite WHY-first. - Stale references to closed Plan IDs or removed types. - Bare `TODO:` / `FIXME:` without issue link. ## Follow the canonical pattern Use the AppDelegate.swift P0 rewrite (#65) as the canonical applied pattern. ## Parent epic #64 ## Source .planning/code-commenting-guide.md → Migration plan → P2
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
area:agent
area:build
area:bus
area:devtool
area:hud
area:logging
area:mcp
area:memory
area:vision
area:voice
audit-finding
bug
Something isn't working
 carry-forward
comment-cleanup
Comment / docstring cleanup per .planning/code-commenting-guide.md
 dependencies
Dependency updates
 documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 epic
good first issue
Good for newcomers
 help wanted
Extra attention is needed
 invalid
This doesn't seem right
 javascript
Pull requests that update javascript code
 migration
question
Further information is requested
 severity:critical
severity:high
severity:low
severity:medium
wontfix
This will not be worked on
No labels area:voice comment-cleanup enhancement severity:medium
Milestone
No items
No Milestone v1.0 — Shipping (commenting, behavioral gates, first-launch polish)
Projects
Clear projects
No projects
Assignees
Clear assignees
forge-recovery (Forge Recovery) james.maes (James Maes)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: KofTwentyTwo/Jarvis#70