Repository navigation
docs(examine): say a Device's path is the logical host path - #642
Conversation
stat_device documents that it reads a node through host_path but reports the logical path. That invariant belongs on the public, serialized Device too, where a consumer of `rocm examine --json` will look for it. Follows up the review on #510. Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
jussielo-amd
left a comment
There was a problem hiding this comment.
Reviewed against the merge-base with origin/main (7a062ad) at head db7203b.
This is a precise, narrow follow-up: it implements exactly the one-line note asked for in the #510 approval ("stat_device documents that it reads through host_path but reports the logical path, but that invariant isn't mirrored onto the public, serialized Device struct's own doc comment... worth a one-line note on the struct at some point, but not blocking"). Traced the claim against the code rather than taking it at face value — stat_device (examine.rs:1779-1788) does assign path: path.to_owned() (the logical path) while only using the re-rooted host_path(path) for the actual stat call, so the new doc comment is accurate. The intra-doc link to crate::host_path resolves (it's re-exported in lib.rs), and the two other Device { .. } literals the PR body points to are test fixtures in diagnose.rs, as described.
Verified independently:
cargo fmt --all --check,cargo clippy -p rocm-core --all-targets -- -D warnings— clean.cargo test -p rocm-core --lib examine— 85 passed, 1 ignored, 0 failed.cargo doc -p rocm-core --no-deps— same 7 pre-existing warnings as the merge-base build; no new warning from the added doc comments.- Leak scan against the diff — clean.
- DCO sign-off present; commit signature
verified: valid. - All CI checks green.
Doc-only, no user-observable behavior change, so the PR body's "no scenario needed" claim holds. Nothing blocking.
Follows up #510.
The approval on #510 noted that
stat_devicedocuments that it reads a device node throughhost_pathbut reports the logical path. The public, serializedDevicestruct didn't say so, so a consumer ofrocm examine --jsonwould have to find a private function's comment to learn it.This adds that to the doc comments of
Deviceand itspathfield.stat_deviceis the only production constructor; the otherDevice { .. }literals are test fixtures indiagnose.rs.Doc-only. Verified with
cargo fmt --all --check,cargo test -p rocm-core --lib examine(85 passed),cargo clippy -p rocm-core --all-targets -- -D warnings, andcargo doc -p rocm-core --no-deps, which adds no new warning. No scenario: nothing a CLI user can observe changes.