Skip to content

ROCMAI-849: fix stale and misattached doc comments in dash-tui and apps/rocm - #881

Merged
jussielo-amd merged 4 commits into
ROCm:mainfrom
jussielo-amd:docs/fix-misattached-doc-comments
Nov 5, 2026
Merged

jussielo-amd merged 4 commits into
ROCm:mainfrom
jussielo-amd:docs/fix-misattached-doc-comments

Conversation

@jussielo-amd

@jussielo-amd jussielo-amd commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator

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 of console_scroll_delta's, so console_scroll_delta carried both and handle_mouse had none; the doc now sits above handle_mouse. In app/chat_state.rs, the doc of set_chat_config had been left on accept_chat_consent when the function moved to app/chat.rs; it now documents set_chat_config, and accept_chat_consent keeps its own line. In agent/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). In agent/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_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, and the behavior it describes (canonicalizing the install root next to the symlink-preserving interpreter path) was checked and is still true. The storage.rs module doc linked crate::should_remove_runtime_install_root, which is not at the crate root; the link now points at crate::runtime_uninstall::should_remove_runtime_install_root. The service_launch.rs module doc said main.rs, serve_cmd.rs and automations.rs call into the module, but main.rs only declares it, and services_text.rs, chat.rs, freeform_planner.rs and uninstall_plan.rs call in as well; the doc now says other modules call in and drops the enumeration, which is what had drifted. The automations.rs module doc implied the automations() handler is how watcher_policy_note is reached, but render_automations_text calls 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.rs comment ("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 returns ApprovalRequired, and run_rocm_read_tool turns that into an error. It is not "no writes": the services, service_logs, port_status and bridge_snapshot tools and the rocm_command service 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; doctor and examine can re-register the configured setup runtime in the runtime registry when its entry is missing; and update_check and install_sdk_dry_run cache package-index metadata under the cache folder and, on a host with no usable Python on PATH, can download a managed uv and Python into the data folder and record that Python in the saved config. The comment now says exactly that, and the agent/mod.rs module 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. The detail_modal name in the dash-TUI modal docs is gone (the split of ui/modal.rs removed it; detail_modal now only appears in test names). The managed_runtime.rs module doc no longer calls amd-smi resolution "not-yet-scoped": it says the resolution reads the registry records from crate::amd_smi, a distinct module, and that is true. The chat.rs module doc no longer lists callers, and its claim that only ChatToolApprovalRequest and ChatRocmCommandAction are pub(crate) types matches the code, with ChatRocmCommandAction read only by the driver_plan.rs test module. The managed_service_status.rs module doc already says friendly_engine_label is read only by chat.rs, that services_text.rs renders the local-servers view, and that service_launch.rs is the only caller of existing_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_per doc in the daemon runner (it sits in the function region a separate refactor reshapes), the module docs of engines_cmd.rs, runtimes_cmd.rs and runtime_install_finalize.rs (the import-cycle change rewrites those), and everything about the dash-TUI skills.rs subsystem (a separate removal deletes the file). I also grepped docs/, README.md, AGENTS.md, skills/, crates/ and apps/ for the old wording of each claim; docs/architecture.md already states the correct callers for service_launch.rs and watcher_policy_note, so no other surface repeats a false claim. docs/llm-tool-use.md and skills/rocm-cli-assistant/SKILL.md use "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 main into it with a signed merge commit (no history rewrite): git diff -U0 filtered for changed lines that are not comments prints nothing for the follow-up commit, and the diff of the branch against main touches only the nine .rs files listed above, all of it comment lines; cargo fmt --all --check is clean; cargo clippy -p rocm -p rocm-dash-tui --all-targets -- -D warnings passes (it is worth running even for comment-only changes: a first draft of the agent/mod.rs module doc made its first paragraph too long for clippy::too_long_first_doc_paragraph, and the commit hooks do not run clippy); cargo xtask manifest --check passes; 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 against main shows only the word "private" in "stays private", and the conflict-marker grep is clean.

Not run

The full workspace tests, the tests/e2e-cucumber suite and the Windows lane were not run locally; CI carries them. The intra-doc link in the storage.rs module doc was not checked with cargo doc, since a cold documentation build of the whole rocm crate was outside the time budget; the path it names (runtime_uninstall::should_remove_runtime_install_root) was confirmed by reading the definition in runtime_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 for storage.rs; #820, #819 and #811 for therock.rs; #882 and #812 for agent/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 from agent/tools.rs and agent/mod.rs but not the comment lines this PR rewrites, and the wording added here does not mention them. It does not touch docs/architecture.md.

This is a documentation-only change with no behavior change, so no end-to-end scenario is needed.

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>
@jussielo-amd
jussielo-amd requested a balanced review from Copilot November 4, 2026 11:31
@jussielo-amd
jussielo-amd marked this pull request as ready for review November 4, 2026 11:32
@jussielo-amd
jussielo-amd requested a review from a team as a code owner November 4, 2026 11:32

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread crates/rocm-dash-tui/src/agent/tools.rs Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The approval-boundary comment incorrectly promises mutation-free reads even though the services tool persists refreshed service records, including liveness-driven status changes.

1 open issue

Review effort: Balanced

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 nowycondro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 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 calls executor.execute(...) and returns its Result/Error/ApprovalRequired variant; it never calls execute_approved. The mutating tools (rocm_mutating_tool!) likewise only forward ApprovalRequired to approval_tx and return a "surfaced" note, never executing — this is backed by the existing test mutating_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 underlying services tool can persist refreshed/liveness-derived service records to disk; that behavior (if real) lives in a different crate/file entirely (the bin-supplied SharedRocmToolExecutor implementation), 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_probe exists and really does canonicalize the install root while preserving the interpreter path's symlink via absolute_existing_file_path_preserving_symlink; runtime_uninstall::should_remove_runtime_install_root exists at the named path; automations() and render_automations_text in automations.rs both genuinely call watcher_policy_note locally; and service_launch.rs's callers (services_text.rs, chat.rs, freeform_planner.rs, uninstall_plan.rs) all genuinely reference service_launch::, while main.rs contains only the bare mod service_launch; declaration. This is an unusually well-verified doc-only PR.
  • The actions.rs doc relocation is clean: handle_mouse's doc now sits directly above it with no leftover duplicate, and console_scroll_delta keeps 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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for this documentation cleanup.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 5, 2026
Merged via the queue into ROCm:main with commit 4bf04a6 Nov 5, 2026
30 checks passed
@jussielo-amd
jussielo-amd deleted the docs/fix-misattached-doc-comments branch November 5, 2026 06:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants