Repository navigation
ROCMAI-849: fix stale and misattached doc comments in dash-tui and apps/rocm - #881
Conversation
handle_mouse's doc sat on top of console_scroll_delta's, so handle_mouse had none and console_scroll_delta carried both. The doc is now directly above handle_mouse. set_chat_config's doc had been left on accept_chat_consent in chat_state.rs when the function moved to chat.rs. It now documents set_chat_config, and accept_chat_consent keeps its own. The comment above the read-only ROCm tools in agent/tools.rs said no mutating tool is registered and that mutating tools land in a later phase, but the mutating tools are declared in the same file. It now says that nothing in the read-only group mutates anything and that the mutating group only surfaces an approval request. The agent module doc described a read-only agent and now covers the tool set as it is. Comment changes only. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
resolved_install_root in therock.rs cited main::adopt_runtime_from_probe, which lives in runtime_adopt.rs; the comment now names runtime_adopt::adopt_runtime_from_probe. The behavior it describes (canonicalizing the install root next to the symlink-preserving interpreter path) is unchanged and still true. The storage.rs module doc linked [crate::should_remove_runtime_install_root], which is not at the crate root. It is defined in runtime_uninstall.rs, so the link now points there. The service_launch.rs module doc said main.rs, serve_cmd.rs and automations.rs call into the module. main.rs only declares it; the doc now says other modules call in rather than listing them, since the list had drifted (services_text.rs, chat.rs, freeform_planner.rs and uninstall_plan.rs also call in). The automations.rs module doc implied the automations() handler is how watcher_policy_note is reached. render_automations_text calls it too, and the doc now says both do. Comment changes only. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
There was a problem hiding this comment.
🟡 Changes recommended
The new comment incorrectly guarantees no mutations, although service-status loading can write bookkeeping updates to disk.
1 open issue
What changed in this PR
This documentation-only PR addresses stale and misplaced Rust comments found during the modularization audit. It aligns dash-TUI and CLI documentation with existing code without changing runtime behavior.
Changes:
- Moves mouse-handling and chat-configuration docs onto the functions they describe.
- Updates agent documentation to describe read tools and approval-gated mutating tools.
- Corrects CLI module paths, intra-doc links, and caller descriptions.
| File | Description |
|---|---|
crates/rocm-dash-tui/src/app/chat.rs |
Adds the relocated set_chat_config documentation. |
crates/rocm-dash-tui/src/app/chat_state.rs |
Removes unrelated docs from accept_chat_consent. |
crates/rocm-dash-tui/src/app/actions.rs |
Moves mouse-handling docs onto handle_mouse. |
crates/rocm-dash-tui/src/agent/tools.rs |
Replaces the obsolete claim that mutating tools are not registered. |
crates/rocm-dash-tui/src/agent/mod.rs |
Describes the current tool set and approval flow. |
apps/rocm/src/therock.rs |
Corrects the documented location of the runtime-adoption helper. |
apps/rocm/src/storage.rs |
Corrects the intra-doc link to the runtime-removal guard. |
apps/rocm/src/service_launch.rs |
Removes the stale caller enumeration. |
apps/rocm/src/automations.rs |
Documents both local callers of watcher_policy_note. |
Review effort: Balanced
juhovainio
left a comment
There was a problem hiding this comment.
Looks good. This is a comment-only change: every changed line is a doc comment or a moved doc block, so there is no behavior change. I checked each corrected comment against the code it describes and they are accurate. That covers the handle_mouse and set_chat_config doc moves, the mutating-tool wording in tools.rs and agent/mod.rs, and the symbols cited in therock.rs, storage.rs, service_launch.rs and automations.rs. Scope matches ROCMAI-849.
Two caveats. The intra-doc link in storage.rs was not built with cargo doc; the target, runtime_uninstall::should_remove_runtime_install_root, does exist and is pub(crate). This is also a diff-only read: when I looked, the Strix Halo Ubuntu E2E lanes had failed and the MI300X and W7900 lanes were still pending. With a comment-only change these are most likely hardware or infra problems, but please re-check them once the run finishes.
nowycondro
left a comment
There was a problem hiding this comment.
🤖 Automated review (Claude Code) · 96d10e0
This automation never files a GitHub approval, so no approving review will appear here whatever the outcome — the merge decision stays with a human reviewer.
Review — no blocking findings
DEGRADED REVIEW (partial): the planned independent multi-worker fan-out required by this review's method could not be confirmed complete in this environment (a shared subagent-concurrency limit blocked three of six planned passes outright, and a purported relay of "worker findings" for the other three could not be verified as genuinely produced by those workers, so it was discarded rather than used as evidence). What follows is a direct, single-context verification pass: every one of the 9 changed files was read in full at the reviewed commit, plus the cross-referenced files needed to check each claim (runtime_uninstall.rs, runtime_adopt.rs, main.rs, services_text.rs, chat.rs, freeform_planner.rs, uninstall_plan.rs, AGENTS.md), using direct GitHub API/raw-content reads pinned to the exact head SHA rather than GitHub's code-search index (which was observed to lag behind this PR's commits and returned pre-fix content when queried).
This implements ROCm JIRA ROCMAI-849 ("fix stale and misattached doc comments," PR 3 of 7 of Phase 8.1-H / ROCMAI-760), and the PR body's description of what changed matches the actual diff closely. One minor, non-blocking divergence from the ticket's own wording: the ticket says adopt_runtime_from_probe "now lives in runtimes_cmd.rs," but it is actually defined in runtime_adopt.rs (confirmed by reading the function definition) — the PR correctly points there instead, and its body explains that items were "re-checked against the current tree... because several had moved since the audit," which accounts for this.
Blocking
None.
Non-blocking
None.
Decisions for the author
agent/tools.rs's "nothing in this group mutates anything" claim, scoped to the read-only tool wrappers in this file — tradeoff/wording. Read directly: every read-only tool (run_rocm_read_tool) only ever callsexecutor.execute(...)and returns itsResult/Error/ApprovalRequiredvariant; it never callsexecute_approved. The mutating tools (rocm_mutating_tool!) likewise only forwardApprovalRequiredtoapproval_txand return a "surfaced" note, never executing — this is backed by the existing testmutating_tool_surfaces_approval_not_execution, which asserts the approved-execution path is never reached from the rig loop. So the comment is accurate for the Rust code in this file. GitHub Copilot's review on this PR flagged that the underlyingservicestool can persist refreshed/liveness-derived service records to disk; that behavior (if real) lives in a different crate/file entirely (the bin-suppliedSharedRocmToolExecutorimplementation), which this PR does not touch and the comment does not make claims about. Worth a one-line tightening (e.g. "mutates nothing in this crate") if the author wants to preempt the question, but it is not a misstatement of what this file's code does.
Positive signals
- Every cross-reference this PR introduces was checked against the real definition site and found accurate:
runtime_adopt::adopt_runtime_from_probeexists and really does canonicalize the install root while preserving the interpreter path's symlink viaabsolute_existing_file_path_preserving_symlink;runtime_uninstall::should_remove_runtime_install_rootexists at the named path;automations()andrender_automations_textinautomations.rsboth genuinely callwatcher_policy_notelocally; andservice_launch.rs's callers (services_text.rs,chat.rs,freeform_planner.rs,uninstall_plan.rs) all genuinely referenceservice_launch::, whilemain.rscontains only the baremod service_launch;declaration. This is an unusually well-verified doc-only PR. - The
actions.rsdoc relocation is clean:handle_mouse's doc now sits directly above it with no leftover duplicate, andconsole_scroll_deltakeeps its own single doc comment.
Deployment notes
None — comment-only change, no behavior, no migration.
What this covered
Read directly and completely, at commit a537f1a92812…96d10e026568: apps/rocm/src/automations.rs, apps/rocm/src/service_launch.rs, apps/rocm/src/storage.rs, apps/rocm/src/therock.rs (diff region) plus apps/rocm/src/runtime_uninstall.rs and apps/rocm/src/runtime_adopt.rs in full for cross-reference, crates/rocm-dash-tui/src/agent/mod.rs, crates/rocm-dash-tui/src/agent/tools.rs, crates/rocm-dash-tui/src/app/actions.rs (diff region, confirmed via raw fetch), crates/rocm-dash-tui/src/app/chat.rs, crates/rocm-dash-tui/src/app/chat_state.rs, plus apps/rocm/src/main.rs (module declarations), services_text.rs/chat.rs/freeform_planner.rs/uninstall_plan.rs (grepped for service_launch:: usage), and the repository's AGENTS.md in full.
Did not run as independent fan-out workers: agent-instruction-adherence, history (git log/blame), and prior-changes-on-these-files passes were blocked by a shared subagent concurrency limit in this environment and never completed; their substance (AGENTS.md compliance, cross-reference accuracy) was instead covered directly in this single-context pass as described above. CI: all 32 checks on this commit completed, success or skipped, none failing. No nowycondro review existed at this head SHA at time of posting (re-checked immediately before publishing). Not reconciled against PR discussion beyond the two Copilot review comments, which were read only to the extent needed to independently verify (not assume) the one substantive technical claim they raised, addressed above.
🤖 Generated with Claude Code
…doc-comments Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The comment above the read-only ROCm tools said nothing in the group mutates anything, which is stronger than the code. None of these tools performs an action that needs operator approval, but reading can still refresh local bookkeeping: loading managed services rewrites a record whose state changed, examine can re-register the configured setup runtime, and the update check and SDK dry run cache package-index metadata and may provision a managed uv and Python. The comment now states the approval-sense guarantee and lists those side effects, and the agent module doc points at it instead of calling the tools plainly read-only. Comment text only. Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Why
The modularization audit found doc comments that describe code that has since moved or never matched it: a doc attached to the wrong function, a comment saying a mutating tool does not exist next to the mutating tools, and module docs that name the wrong caller or the wrong path. A comment that disagrees with the code costs the next reader time, and a few of them were repeated as a claim in a module doc. This is part of the follow-up work from the modularization audit; it changes comment lines only. Completes ROCMAI-849.
What changes
Three commits: one per area, plus a follow-up from review. Every item was re-checked against the current tree before it was touched, because several had moved since the audit.
The dash-TUI commit fixes five items. In
app/actions.rs,handle_mouse's doc comment sat directly on top ofconsole_scroll_delta's, soconsole_scroll_deltacarried both andhandle_mousehad none; the doc now sits abovehandle_mouse. Inapp/chat_state.rs, the doc ofset_chat_confighad been left onaccept_chat_consentwhen the function moved toapp/chat.rs; it now documentsset_chat_config, andaccept_chat_consentkeeps its own line. Inagent/tools.rs, the comment above the read-only ROCm tools said no mutating tool is registered and that mutating tools would arrive in a later phase, but the mutating tools are declared further down the same file; the comment now describes the group as it is (see the follow-up commit for its exact wording). Inagent/mod.rs, the module doc described a read-only agent and now describes the tool set as it is: telemetry tools, read-only ROCm tools, and mutating ROCm tools that post their intent on the approval channel and never run inside the model's tool loop.The apps/rocm commit fixes four items.
resolved_install_rootintherock.rscitedmain::adopt_runtime_from_probe, which lives inruntime_adopt.rs; the comment now namesruntime_adopt::adopt_runtime_from_probe, and the behavior it describes (canonicalizing the install root next to the symlink-preserving interpreter path) was checked and is still true. Thestorage.rsmodule doc linkedcrate::should_remove_runtime_install_root, which is not at the crate root; the link now points atcrate::runtime_uninstall::should_remove_runtime_install_root. Theservice_launch.rsmodule doc saidmain.rs,serve_cmd.rsandautomations.rscall into the module, butmain.rsonly declares it, andservices_text.rs,chat.rs,freeform_planner.rsanduninstall_plan.rscall in as well; the doc now says other modules call in and drops the enumeration, which is what had drifted. Theautomations.rsmodule doc implied theautomations()handler is howwatcher_policy_noteis reached, butrender_automations_textcalls it too, and the doc now says both do.The follow-up commit answers the review finding that the first wording of the
agent/tools.rscomment ("nothing in this group mutates anything") was stronger than the code. Reading the implementation of each read-only tool showed the guarantee that holds is the approval-sense one: none of the tools performs an install, start, stop, uninstall, configuration change or anything else that needs operator approval, because the bin classifies such an intent as mutating, the executor returnsApprovalRequired, andrun_rocm_read_toolturns that into an error. It is not "no writes": theservices,service_logs,port_statusandbridge_snapshottools and therocm_commandservice views load the managed-service records, which rewrites a record whose state changed and drops the endpoint key of a service whose requested stop has finished;doctorandexaminecan re-register the configured setup runtime in the runtime registry when its entry is missing; andupdate_checkandinstall_sdk_dry_runcache package-index metadata under the cache folder and, on a host with no usable Python on PATH, can download a manageduvand Python into the data folder and record that Python in the saved config. The comment now says exactly that, and theagent/mod.rsmodule doc no longer calls the ROCm tools plainly read-only and points at that comment. Comment text only, like the rest of the PR.Items found already fixed
Four items on the list needed no change on current
main, so I left them alone. Thedetail_modalname in the dash-TUI modal docs is gone (the split ofui/modal.rsremoved it;detail_modalnow only appears in test names). Themanaged_runtime.rsmodule doc no longer calls amd-smi resolution "not-yet-scoped": it says the resolution reads the registry records fromcrate::amd_smi, a distinct module, and that is true. Thechat.rsmodule doc no longer lists callers, and its claim that onlyChatToolApprovalRequestandChatRocmCommandActionarepub(crate)types matches the code, withChatRocmCommandActionread only by thedriver_plan.rstest module. Themanaged_service_status.rsmodule doc already saysfriendly_engine_labelis read only bychat.rs, thatservices_text.rsrenders the local-servers view, and thatservice_launch.rsis the only caller ofexisting_live_managed_service, all of which match the call sites.Three other items are deliberately not in this PR because other tickets own them: the
ticks_perdoc in the daemon runner (it sits in the function region a separate refactor reshapes), the module docs ofengines_cmd.rs,runtimes_cmd.rsandruntime_install_finalize.rs(the import-cycle change rewrites those), and everything about the dash-TUIskills.rssubsystem (a separate removal deletes the file). I also greppeddocs/,README.md,AGENTS.md,skills/,crates/andapps/for the old wording of each claim;docs/architecture.mdalready states the correct callers forservice_launch.rsandwatcher_policy_note, so no other surface repeats a false claim.docs/llm-tool-use.mdandskills/rocm-cli-assistant/SKILL.mduse "read-only" only in the approval sense (a read-only check runs without the approval screen), which is what the new comment now says too, so they need no change.Verification
Run locally on the final branch, after merging current
maininto it with a signed merge commit (no history rewrite):git diff -U0filtered for changed lines that are not comments prints nothing for the follow-up commit, and the diff of the branch againstmaintouches only the nine.rsfiles listed above, all of it comment lines;cargo fmt --all --checkis clean;cargo clippy -p rocm -p rocm-dash-tui --all-targets -- -D warningspasses (it is worth running even for comment-only changes: a first draft of theagent/mod.rsmodule doc made its first paragraph too long forclippy::too_long_first_doc_paragraph, and the commit hooks do not run clippy);cargo xtask manifest --checkpasses; the repository's pre-commit hooks passed on every commit (whitespace, merge-conflict markers, commit signing and sign-off, license headers, markdown links,cargo fmt); the leak scan over the diff againstmainshows only the word "private" in "stays private", and the conflict-marker grep is clean.Not run
The full workspace tests, the
tests/e2e-cucumbersuite and the Windows lane were not run locally; CI carries them. The intra-doc link in thestorage.rsmodule doc was not checked withcargo doc, since a cold documentation build of the wholerocmcrate was outside the time budget; the path it names (runtime_uninstall::should_remove_runtime_install_root) was confirmed by reading the definition inruntime_uninstall.rs.Overlaps and scope
Many open PRs touch these files for unrelated reasons (for example #859, #857, #854 and #817 for
service_launch.rs; #853 and #815 forstorage.rs; #820, #819 and #811 fortherock.rs; #882 and #812 foragent/tools.rs), but this change only edits a handful of comment lines at the top of each file or in a doc block, so a textual conflict is unlikely and would be trivial. #882 removes the skill-registry tools fromagent/tools.rsandagent/mod.rsbut not the comment lines this PR rewrites, and the wording added here does not mention them. It does not touchdocs/architecture.md.This is a documentation-only change with no behavior change, so no end-to-end scenario is needed.