kayg/calternal

Watch

Fork 0

DOCS: remove product names and explain server API helpers #918

New issue

Open

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

kayg commented

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

Owner

Evidence

At the #863 audit base, a case-sensitive scan found 26 comment lines in 5 files under crates/calternal-server/src that name common third-party products. Examples: wire.rs:198 and :203 name a platform profile format; :728 describes collection display state.
The public-function scan found four functions without adjacent comments, including wire.rs:1068 (build_live_app) and :1706 (reindex).

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 app construction and reindex side effects. Describe profile signing inputs and collection state without product names. Preserve routes, schema, and runtime behavior.

Test idea

Review comments against the server API and route tests. Run a source scan for product names. Do not change API or test expectations.

## Evidence At the #863 audit base, a case-sensitive scan found 26 comment lines in 5 files under `crates/calternal-server/src` that name common third-party products. Examples: `wire.rs:198` and `:203` name a platform profile format; `:728` describes collection display state. The public-function scan found four functions without adjacent comments, including `wire.rs:1068` (`build_live_app`) and `:1706` (`reindex`). ## 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 app construction and reindex side effects. Describe profile signing inputs and collection state without product names. Preserve routes, schema, and runtime behavior. ## Test idea Review comments against the server API and route tests. Run a source scan for product names. Do not change API or 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:53:21 +00:00

Author

Owner

Fixed the Rust comment findings in crates/calternal-server. Explain live setup and reindex side effects. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: 23fb95c324fd87dbc62930c0a9e27204f38ea705.

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-server/src/appearance.rs
crates/calternal-server/src/main.rs
crates/calternal-server/src/mcp.rs
crates/calternal-server/src/notes_imap.rs
crates/calternal-server/src/serve.rs
crates/calternal-server/src/wire.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-server`. Explain live setup and reindex side effects. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `23fb95c324fd87dbc62930c0a9e27204f38ea705`. 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-server/src/appearance.rs` - `crates/calternal-server/src/main.rs` - `crates/calternal-server/src/mcp.rs` - `crates/calternal-server/src/notes_imap.rs` - `crates/calternal-server/src/serve.rs` - `crates/calternal-server/src/wire.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: explain live setup and reindex side effects (#918)

kayg commented

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

Author

Owner

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

docs: explain live setup and reindex side effects (#918)

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-server/src/appearance.rs
crates/calternal-server/src/head.rs
crates/calternal-server/src/main.rs
crates/calternal-server/src/mcp.rs
crates/calternal-server/src/notes_imap.rs
crates/calternal-server/src/serve.rs
crates/calternal-server/src/wire.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: `26c07f4d7b76bf87cd9ad221aea41644bd96fee8`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: explain live setup and reindex side effects (#918) 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-server/src/appearance.rs` - `crates/calternal-server/src/head.rs` - `crates/calternal-server/src/main.rs` - `crates/calternal-server/src/mcp.rs` - `crates/calternal-server/src/notes_imap.rs` - `crates/calternal-server/src/serve.rs` - `crates/calternal-server/src/wire.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 live setup and reindex side effects (#918)

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#918

No description provided.

Rows
Columns