DOCS: document authentication APIs and remove product names #905

Open
opened 2026-10-02 17:39:09 +00:00 by kayg · 1 comment
Owner

Evidence

At the #863 audit base, a case-sensitive scan found 8 comment lines in 3 files under crates/calternal-auth/src that name common third-party products. Examples: api.rs:54 names Safari and iOS; profile_signing.rs:1 names Apple configuration profiles.
The public-function scan found 32 functions without adjacent doc comments. Non-obvious examples include api.rs:101 (validate) and store.rs:887 (connect).

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 the authentication and session invariants that callers rely on. Describe cookie, profile, and credential compatibility without product names. Preserve protocol behavior and error handling.

Test idea

Review public auth APIs for comments that state inputs, side effects, and invariants. Run a source scan for product names. Keep auth behavior tests unchanged.

## Evidence At the #863 audit base, a case-sensitive scan found 8 comment lines in 3 files under `crates/calternal-auth/src` that name common third-party products. Examples: `api.rs:54` names Safari and iOS; `profile_signing.rs:1` names Apple configuration profiles. The public-function scan found 32 functions without adjacent doc comments. Non-obvious examples include `api.rs:101` (`validate`) and `store.rs:887` (`connect`). ## 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 the authentication and session invariants that callers rely on. Describe cookie, profile, and credential compatibility without product names. Preserve protocol behavior and error handling. ## Test idea Review public auth APIs for comments that state inputs, side effects, and invariants. Run a source scan for product names. Keep auth behavior tests unchanged.
Author
Owner

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

docs(auth): explain validation and Index setup for #905

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-auth/src/api.rs
  • crates/calternal-auth/src/profile_signing.rs
  • crates/calternal-auth/src/store.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: `7368c92f4a47f6a136f64b6314864607c9d910ce`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs(auth): explain validation and Index setup for #905 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-auth/src/api.rs` - `crates/calternal-auth/src/profile_signing.rs` - `crates/calternal-auth/src/store.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.
Sign in to join this conversation.
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#905
No description provided.