kayg/calternal

Watch

Fork 0

DOCS: document saved-place operations #910

New issue

Open

opened 2026-10-02 17:39:26 +00:00 by kayg · 2 comments

kayg commented

2026-10-02 17:39:26 +00:00

Owner

Evidence

At the #863 audit base, the public-function scan found four functions in crates/calternal-location/src/lib.rs without adjacent docs: load at :71, update at :106, match_place at :172, and valid_coordinates at :595. The update and match functions have behavior that is not clear from their signatures alone.

Owner rule

Comments are documentation. Each non-obvious function needs a short, current comment.

Expected behaviour

Document the saved-place read/update behavior, matching rules, and coordinate validity bounds. State any invariants callers must preserve. Keep behavior unchanged.

Test idea

Review the comments against the location tests, including boundary coordinates and matching ties. Do not change existing test expectations.

## Evidence At the #863 audit base, the public-function scan found four functions in `crates/calternal-location/src/lib.rs` without adjacent docs: `load` at :71, `update` at :106, `match_place` at :172, and `valid_coordinates` at :595. The update and match functions have behavior that is not clear from their signatures alone. ## Owner rule Comments are documentation. Each non-obvious function needs a short, current comment. ## Expected behaviour Document the saved-place read/update behavior, matching rules, and coordinate validity bounds. State any invariants callers must preserve. Keep behavior unchanged. ## Test idea Review the comments against the location tests, including boundary coordinates and matching ties. Do not change existing test expectations.

kayg referenced this issue

2026-10-02 17:44:36 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg commented

2026-10-02 17:50:46 +00:00

Author

Owner

Fixed the Rust comment findings in crates/calternal-location. Explain saved-place retries and matching bounds. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: e6a9eba83abbaf49e0f20938a55ebfa45099d630.

Verification: cargo fmt --check exited 0; output was empty. A source comparison with full-line comments removed matched before and after for every changed file.

Files:

crates/calternal-location/src/lib.rs

Decision: use protocol, format, and calternal domain terms in place of product names. No behavior decision. Issues remain open.

Fixed the Rust comment findings in `crates/calternal-location`. Explain saved-place retries and matching bounds. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `e6a9eba83abbaf49e0f20938a55ebfa45099d630`. Verification: `cargo fmt --check` exited 0; output was empty. A source comparison with full-line comments removed matched before and after for every changed file. Files: - `crates/calternal-location/src/lib.rs` Decision: use protocol, format, and calternal domain terms in place of product names. No behavior decision. Issues remain open.

kayg commented

2026-10-02 18:02:31 +00:00

Author

Owner

Rust comment fixes are complete on job/docsfix-rust. Final commit: 52ad590f8cc15354a15ea2ac80411e0265eec5f9. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work.

docs: explain Saved-place retries and matching bounds (#910)

All executable source and test expectations are unchanged. The final comparison against origin/dev confirmed only full-line comments and blank lines changed. The audited product-name scan passed across non-vendored Rust comments.

Gate: cargo fmt --check exited 0. Verbatim stdout and stderr are empty:

Files:

crates/calternal-location/src/lib.rs

Decision: describe existing behavior with protocol, format, and calternal domain terms; no behavior or design change. No build or behavior tests ran, as required by this comment-only job. No issue is closed.

Rust comment fixes are complete on `job/docsfix-rust`. Final commit: `52ad590f8cc15354a15ea2ac80411e0265eec5f9`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: explain Saved-place retries and matching bounds (#910) All executable source and test expectations are unchanged. The final comparison against `origin/dev` confirmed only full-line comments and blank lines changed. The audited product-name scan passed across non-vendored Rust comments. Gate: `cargo fmt --check` exited 0. Verbatim stdout and stderr are empty: ```text ``` Files: - `crates/calternal-location/src/lib.rs` Decision: describe existing behavior with protocol, format, and calternal domain terms; no behavior or design change. No build or behavior tests ran, as required by this comment-only job. No issue is closed.

kayg referenced this issue

2026-10-02 18:02:42 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg referenced this issue from a commit

2026-10-02 18:10:46 +00:00

docs: explain Saved-place retries and matching bounds (#910)

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

kayg/calternal#910

No description provided.

Rows
Columns