Repository navigation
docs: correct stale caller and visibility claims in module comments - #804
Conversation
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>
There was a problem hiding this comment.
🟢 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_releasecaller.
| 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
left a comment
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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".
There was a problem hiding this comment.
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.
| //! 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 |
There was a problem hiding this comment.
Nit: this line runs longer than the rest of the paragraph (~100 cols vs ~80); consider re-wrapping.
There was a problem hiding this comment.
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>
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:
runtime_install_finalize.rsandruntimes_cmd.rssaidruntimes_cmd.rscalls into the SDK-install finalization. It is the other way round:runtime_install_finalize.rscallsactivate_runtime,newest_installed_runtime_manifestandrecover_setup_runtime_registration, andruntimes_cmd.rsreaches back only from its own test module.runtime_install_finalize.rsis also called fromengines_cmd.rs, anddriver_install.rsreadsreal_os_release; both are now named, and the architecture entry namesreal_os_releaseas well.chat.rslisted five callers as if exhaustive; it now says callers in other modules, production and test-only, go throughchat::.managed_service_status.rssaidmain.rsruns the duplicate-launch guard and that sidebar rendering usesfriendly_engine_label; the guard has one caller (service_launch.rs),friendly_engine_labelis read only bychat.rs, andmain.rsuses the liveness helpers for the in-use check behind removal and pruning plusload_managed_servicesfor prune planning and the codex-bridge snapshot.engine_runtime_select.rsnamed the wrongservices_text.rscaller ofstatus_for_readinessand implied non-test code in the module uses it.examine_report_text.rsnamedmain.rs's serve-engine resolution as a reader ofengine_inventory(it isupdate_cmd.rs) and the engine-serve dispatch arm forengine_ruled_out_by_platform(it isassess_model_for_host).chat.rshas twopub(crate)types, not one:ChatRocmCommandActionis read bydriver_install.rs's test module.examine_report_text.rsdescribedrocm models/examine --verbosebranches indispatch(). The catalog is behindrocm model(aliasmodels) with--verbose,dispatch()calls into the module at two points rather than three, andexamine_human_reportis called fromexamine(), notdispatch()directly. Theengines_cmd.rscaller isrender_engine_inventory_text, notengines().docs/architecture.mdstill 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 (thedriver_install.rscaller above), which is fixed in the second commit.cargo fmt --all --check, clippy (including the e2e harness) andcargo testran as the pre-push hooks and passed.python scripts/smoke_local.pyand the fullcargo test --workspace --all-targetsgate were not run locally because nothing but comments changed; CI runs the full gates.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.