kayg/calternal

Watch

Fork 0

DOCS: document DAV contracts and remove product names #908

New issue

Open

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

kayg commented

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

Owner

Evidence

At the #863 audit base, a case-sensitive scan found 29 comment lines in 5 files under crates/calternal-dav/src that name common third-party products. Examples: areas.rs:113 names Apple Calendar; lib.rs:36 describes its UID/resource-name behavior.
The public-function scan found 12 functions without adjacent docs. Non-obvious examples include protocol.rs:614 (router) and reminders.rs:97 (icalendar).

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 DAV routing and reminder serialization invariants. Describe interoperable identifiers and fields by protocol or format behavior, without vendor names. Preserve the wire behavior.

Test idea

Review the comments against the existing CalDAV and reminder tests. Run a source scan for product names. Keep existing status and serialization expectations unchanged.

## Evidence At the #863 audit base, a case-sensitive scan found 29 comment lines in 5 files under `crates/calternal-dav/src` that name common third-party products. Examples: `areas.rs:113` names Apple Calendar; `lib.rs:36` describes its UID/resource-name behavior. The public-function scan found 12 functions without adjacent docs. Non-obvious examples include `protocol.rs:614` (`router`) and `reminders.rs:97` (`icalendar`). ## 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 DAV routing and reminder serialization invariants. Describe interoperable identifiers and fields by protocol or format behavior, without vendor names. Preserve the wire behavior. ## Test idea Review the comments against the existing CalDAV and reminder tests. Run a source scan for product names. Keep existing status and serialization expectations unchanged.

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:49:48 +00:00

Author

Owner

Fixed the Rust comment findings in crates/calternal-dav. Describe dav access and reminder serialization invariants. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: 7db1e3159d75721851d296e96fb816638d4b56e5.

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-dav/src/areas.rs
crates/calternal-dav/src/files.rs
crates/calternal-dav/src/lib.rs
crates/calternal-dav/src/protocol.rs
crates/calternal-dav/src/reminders.rs
crates/calternal-dav/tests/apple_replay.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-dav`. Describe dav access and reminder serialization invariants. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `7db1e3159d75721851d296e96fb816638d4b56e5`. 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-dav/src/areas.rs` - `crates/calternal-dav/src/files.rs` - `crates/calternal-dav/src/lib.rs` - `crates/calternal-dav/src/protocol.rs` - `crates/calternal-dav/src/reminders.rs` - `crates/calternal-dav/tests/apple_replay.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:29 +00:00

Author

Owner

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

docs: describe DAV access and reminder serialization invariants (#908)

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-dav/src/areas.rs
crates/calternal-dav/src/files.rs
crates/calternal-dav/src/lib.rs
crates/calternal-dav/src/protocol.rs
crates/calternal-dav/src/reminders.rs
crates/calternal-dav/tests/apple_replay.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: `8b70d35e8cd07cc3de616652ffc6e32a93a8b7d3`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: describe DAV access and reminder serialization invariants (#908) 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-dav/src/areas.rs` - `crates/calternal-dav/src/files.rs` - `crates/calternal-dav/src/lib.rs` - `crates/calternal-dav/src/protocol.rs` - `crates/calternal-dav/src/reminders.rs` - `crates/calternal-dav/tests/apple_replay.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: describe DAV access and reminder serialization invariants (#908)

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

No description provided.

Rows
Columns