Skip to content

docs: correct stale caller and visibility claims in module comments - #804

Merged
jussielo-amd merged 3 commits into
ROCm:mainfrom
jussielo-amd:docs/correct-stale-module-comments
Oct 30, 2026
Merged

jussielo-amd merged 3 commits into
ROCm:mainfrom
jussielo-amd:docs/correct-stale-module-comments

Conversation

@jussielo-amd

Copy link
Copy Markdown
Collaborator

Summary

#802 corrected docs/architecture.md, but the module-level //! comments in several source files still repeat the claims it fixed. Those comments are now the only places in the repo that contradict the corrected module map. This follow-up brings them in line with the code and with the document, and applies a wording nit from the review of #802. It changes comments and one doc line only; no code changes.

What was wrong and is now corrected:

  • Reversed call direction. The headers of runtime_install_finalize.rs and runtimes_cmd.rs said runtimes_cmd.rs calls into the SDK-install finalization. It is the other way round: runtime_install_finalize.rs calls activate_runtime, newest_installed_runtime_manifest and recover_setup_runtime_registration, and runtimes_cmd.rs reaches back only from its own test module. runtime_install_finalize.rs is also called from engines_cmd.rs, and driver_install.rs reads real_os_release; both are now named, and the architecture entry names real_os_release as well.
  • Incomplete or wrong caller lists. chat.rs listed five callers as if exhaustive; it now says callers in other modules, production and test-only, go through chat::. managed_service_status.rs said main.rs runs the duplicate-launch guard and that sidebar rendering uses friendly_engine_label; the guard has one caller (service_launch.rs), friendly_engine_label is read only by chat.rs, and main.rs uses the liveness helpers for the in-use check behind removal and pruning plus load_managed_services for prune planning and the codex-bridge snapshot. engine_runtime_select.rs named the wrong services_text.rs caller of status_for_readiness and implied non-test code in the module uses it. examine_report_text.rs named main.rs's serve-engine resolution as a reader of engine_inventory (it is update_cmd.rs) and the engine-serve dispatch arm for engine_ruled_out_by_platform (it is assess_model_for_host).
  • Visibility. chat.rs has two pub(crate) types, not one: ChatRocmCommandAction is read by driver_install.rs's test module.
  • Entry points that do not exist. examine_report_text.rs described rocm models/examine --verbose branches in dispatch(). The catalog is behind rocm model (alias models) with --verbose, dispatch() calls into the module at two points rather than three, and examine_human_report is called from examine(), not dispatch() directly. The engines_cmd.rs caller is render_engine_inventory_text, not engines().
  • Review nit from docs(architecture): correct stale and inaccurate module descriptions #802. The "variant" sentence in docs/architecture.md still said clusters "own private types" while the entries below say "owns types".

How this was checked

Every changed claim was re-derived from the code rather than from the document: callers by grep across apps/rocm/src, enclosing functions and whether a call site sits in production code or a #[cfg(test)] module by reading the surrounding lines, and visibility from the declarations. An independent review of the branch in a fresh context found no blocking findings and one gap (the driver_install.rs caller above), which is fixed in the second commit.

  • cargo fmt --all --check, clippy (including the e2e harness) and cargo test ran as the pre-push hooks and passed. python scripts/smoke_local.py and the full cargo test --workspace --all-targets gate were not run locally because nothing but comments changed; CI runs the full gates.
  • Markdown link check (lychee) passed on the touched document, and the leak scan over the diff only hits the Rust word "private" and function names containing "internal".

Notes

No Gherkin scenario is added: this changes comments and documentation only, with no user-observable CLI behaviour. The remaining design points raised in the review of #802 (exhaustive "no caller outside this module" wording, and PR-number citations that lychee cannot check offline) are deliberate tradeoffs and are not changed here.

The module-level doc comments for chat, runtime_install_finalize,
runtimes_cmd, managed_service_status, engine_runtime_select and
examine_report_text still repeated claims that docs/architecture.md
corrected in ROCm#802: reversed call directions between runtime_install_finalize
and runtimes_cmd, incomplete or wrong caller lists, a second pub(crate) type
in chat.rs, and `rocm models`/`examine --verbose` entry points that do not
exist. Bring each comment in line with the code, and align the remaining
"own private types" wording in architecture.md with the relabelled entries.

Comment-only; no code changes.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
driver_install.rs calls real_os_release from runtime_install_finalize in
production code, so the module comment and the architecture entry should
name it. Also rewrap an over-long comment line in managed_service_status.rs.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd requested a balanced review from Copilot October 30, 2026 11:29
@jussielo-amd
jussielo-amd marked this pull request as ready for review October 30, 2026 11:29
@jussielo-amd
jussielo-amd requested a review from a team as a code owner October 30, 2026 11:29
@jussielo-amd
jussielo-amd requested a review from fredespi October 30, 2026 11:29

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 remain for this comments-and-documentation update aligning module descriptions with the corrected architecture map.

No open issues 🎉

What changed in this PR

This comments-and-documentation-only follow-up to #802 aligns source module descriptions with the corrected architecture map. It does not change executable code or CLI behavior.

Changes:

  • Corrects dependency direction and production versus test-only caller descriptions.
  • Fixes visibility claims and model/examine entry-point descriptions.
  • Updates architecture wording about owned types and documents the real_os_release caller.
File Description
docs/​architecture.md Clarifies type ownership and adds the real_os_release caller.
apps/​rocm/​src/​runtimes_cmd.rs Corrects the dependency direction between runtime modules.
apps/​rocm/​src/​runtime_install_finalize.rs Corrects caller descriptions and runtime activation direction.
apps/​rocm/​src/​managed_service_status.rs Clarifies callers of liveness, sidebar, and duplicate-launch helpers.
apps/​rocm/​src/​examine_report_text.rs Corrects CLI entry points and rendering-helper callers.
apps/​rocm/​src/​engine_runtime_select.rs Identifies the correct readiness caller and test-only local usage.
apps/​rocm/​src/​chat.rs Corrects type visibility and generalizes cross-module caller wording.

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. I checked each corrected claim against the code (visibility of the chat.rs types, the status_for_readiness, engine_inventory, engine_ruled_out_by_platform and managed_service_status callers, and the call direction between runtime_install_finalize.rs and runtimes_cmd.rs) and they all hold. The docs/architecture.md entry is consistent with them.

No blocking issues. Two small comment-wrapping nits are inline. Separately, exact caller lists in module headers will drift again (this is the second correction round after #802); you already acknowledge that tradeoff in the PR body, so it is your call whether to soften them to "for example" or drop them.

This reflects a read of the diff and the code it describes; CI is still running on the heavier lanes.

//! `main.rs`'s `install()` (the SDK-install path) and from the sibling
//! `runtimes_cmd.rs` (runtime activation). `SdkInstallConsents` stays
//! `main.rs`'s `install()` (the SDK-install path), from `engines_cmd.rs`
//! (engine install) and, for `real_os_release`, from `driver_install.rs`. It calls into the sibling `runtimes_cmd.rs` for runtime

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.

Nit: this line is ~130 chars and the rewrap leaves SdkInstallConsents stays as a short stub a couple of lines down. Consider re-wrapping the paragraph to the surrounding ~80-col width, and splitting "who calls this module" from "what this module calls".

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 22511fd: the header is re-wrapped to the surrounding width, the SdkInstallConsents sentence is no longer a stub, and the paragraph is split into who calls this module and what it calls. No wording of any claim changed.

Comment thread apps/rocm/src/managed_service_status.rs Outdated
//! runtime activation; `service_launch.rs` is the only caller of the
//! `existing_live_managed_service` duplicate-launch guard it runs before
//! spawning a new managed service. Shared types/config (`ManagedServiceRecord`,
//! `AppPaths`) and the `endpoint_keys` module stay reachable through `crate::`/`rocm_core::`, as

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.

Nit: this line runs longer than the rest of the paragraph (~100 cols vs ~80); consider re-wrapping.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 22511fd: the long line is re-wrapped to the width of the rest of the paragraph. No wording changed.

Review nits on the module comments: one line in runtime_install_finalize.rs
and one in managed_service_status.rs ran well past the surrounding width, and
the runtime_install_finalize.rs header mixed who calls the module with what it
calls. Rewrap and separate the two; no wording of any claim changes.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd added this pull request to the merge queue Oct 30, 2026
Merged via the queue into ROCm:main with commit 9301dfc Oct 30, 2026
24 checks passed
@jussielo-amd
jussielo-amd deleted the docs/correct-stale-module-comments branch October 30, 2026 12: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.

3 participants