Skip to content

docs(examine): say a Device's path is the logical host path - #642

Merged
rominf merged 1 commit into
mainfrom
docs/examine-device-logical-path
Oct 13, 2026
Merged

rominf merged 1 commit into
mainfrom
docs/examine-device-logical-path

Conversation

@rominf

@rominf rominf commented Oct 12, 2026

Copy link
Copy Markdown
Collaborator

Follows up #510.

The approval on #510 noted that stat_device documents that it reads a device node through host_path but reports the logical path. The public, serialized Device struct didn't say so, so a consumer of rocm examine --json would have to find a private function's comment to learn it.

This adds that to the doc comments of Device and its path field. stat_device is the only production constructor; the other Device { .. } literals are test fixtures in diagnose.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, and cargo doc -p rocm-core --no-deps, which adds no new warning. No scenario: nothing a CLI user can observe changes.

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>
@rominf
rominf requested a review from a team as a code owner October 12, 2026 12:14
@rominf
rominf requested a review from johnl-amd October 12, 2026 12:14

@jussielo-amd jussielo-amd 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.

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.

@rominf
rominf added this pull request to the merge queue Oct 13, 2026
Merged via the queue into main with commit 9597bee Oct 13, 2026
31 checks passed
@rominf
rominf deleted the docs/examine-device-logical-path branch October 13, 2026 09:09
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.

2 participants