kayg/calternal

Watch

Fork 0

DOCS: explain sync APIs and remove product names #920

New issue

Open

opened 2026-10-02 17:40:08 +00:00 by kayg · 2 comments

kayg commented

2026-10-02 17:40:08 +00:00

Owner

Evidence

At the #863 audit base, a case-sensitive scan found 8 comment lines in 5 files under crates/calternal-sync/src that name common third-party products. Examples: credentials.rs:1 names platform keychains; journal.rs:240 and :370 name Finder tag baselines.
The public-function scan found 44 functions without adjacent docs. Non-obvious examples include engine.rs:135 (reconcile_once), :139 (reconcile_once_confirmed), and config.rs:140 (load).

Owner rule

Comments are documentation. Each non-obvious function needs a short, current comment. Source comments must not name third-party products.

Expected behaviour

Document reconciliation confirmation, config loading, and journal invariants. Describe tag storage and credential-store behavior in format or capability terms. Keep sync behavior unchanged.

Test idea

Review docs against existing sync and journal tests. Run a source scan for product names. Do not change collision or recovery expectations.

## Evidence At the #863 audit base, a case-sensitive scan found 8 comment lines in 5 files under `crates/calternal-sync/src` that name common third-party products. Examples: `credentials.rs:1` names platform keychains; `journal.rs:240` and `:370` name Finder tag baselines. The public-function scan found 44 functions without adjacent docs. Non-obvious examples include `engine.rs:135` (`reconcile_once`), `:139` (`reconcile_once_confirmed`), and `config.rs:140` (`load`). ## Owner rule Comments are documentation. Each non-obvious function needs a short, current comment. Source comments must not name third-party products. ## Expected behaviour Document reconciliation confirmation, config loading, and journal invariants. Describe tag storage and credential-store behavior in format or capability terms. Keep sync behavior unchanged. ## Test idea Review docs against existing sync and journal tests. Run a source scan for product names. Do not change collision or recovery 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:54:14 +00:00

Author

Owner

Fixed the Rust comment findings in crates/calternal-sync. Document per-pass confirmation and durable sync baselines. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: 97bed205fe97eedc40bb7a2bab9bfb182e989cdf.

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-sync/src/config.rs
crates/calternal-sync/src/credentials.rs
crates/calternal-sync/src/engine.rs
crates/calternal-sync/src/finder_tags.rs
crates/calternal-sync/src/journal.rs
crates/calternal-sync/src/lib.rs
crates/calternal-sync/src/local.rs
crates/calternal-sync/src/remote.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-sync`. Document per-pass confirmation and durable sync baselines. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `97bed205fe97eedc40bb7a2bab9bfb182e989cdf`. 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-sync/src/config.rs` - `crates/calternal-sync/src/credentials.rs` - `crates/calternal-sync/src/engine.rs` - `crates/calternal-sync/src/finder_tags.rs` - `crates/calternal-sync/src/journal.rs` - `crates/calternal-sync/src/lib.rs` - `crates/calternal-sync/src/local.rs` - `crates/calternal-sync/src/remote.rs` Decision: use protocol, format, and calternal domain terms in place of product names. No behavior decision. Issues remain open.

kayg referenced this issue from a commit

2026-10-02 17:56:13 +00:00

docs: document per-pass confirmation and durable sync baselines (#920)

kayg commented

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

Author

Owner

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

docs: document per-pass confirmation and durable sync baselines (#920)

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-sync/src/config.rs
crates/calternal-sync/src/credentials.rs
crates/calternal-sync/src/engine.rs
crates/calternal-sync/src/finder_tags.rs
crates/calternal-sync/src/journal.rs
crates/calternal-sync/src/lib.rs
crates/calternal-sync/src/local.rs
crates/calternal-sync/src/remote.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: `5a1664b469676eb744a0402bed6d389d60b3ea92`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: document per-pass confirmation and durable sync baselines (#920) 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-sync/src/config.rs` - `crates/calternal-sync/src/credentials.rs` - `crates/calternal-sync/src/engine.rs` - `crates/calternal-sync/src/finder_tags.rs` - `crates/calternal-sync/src/journal.rs` - `crates/calternal-sync/src/lib.rs` - `crates/calternal-sync/src/local.rs` - `crates/calternal-sync/src/remote.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: document per-pass confirmation and durable sync baselines (#920)

kayg referenced this issue

2026-10-03 00:35:56 +00:00

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

kayg referenced this issue

2026-10-03 00:35:56 +00:00

DOCS: remove product names from AI provider comments #923