DOCS: document Notes plugin operations and remove product names #932

New issue

Open

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

kayg commented

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

Owner

Evidence

At the #863 audit base, a case-sensitive scan found 39 comment lines in 4 files under crates/plugins/notes/src that name third-party products.
The public-function scan found 21 functions without adjacent docs. Non-obvious examples include store.rs:648 (recover_dav), :1931 (reconcile_user), and :1992 (move_note). Comments in imap.rs:98,167,223 also name product-specific wrapper and date behavior.

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 recovery, reconciliation, note movement, and IMAP byte-revision invariants. Describe wrapper bytes and date evidence in protocol terms. Keep mutation and merge behavior unchanged.

Test idea

Review comments against existing Notes, IMAP, DAV, and recovery tests. Run a source scan for product names. Do not change merge or status expectations.

## Evidence At the #863 audit base, a case-sensitive scan found 39 comment lines in 4 files under `crates/plugins/notes/src` that name third-party products. The public-function scan found 21 functions without adjacent docs. Non-obvious examples include `store.rs:648` (`recover_dav`), `:1931` (`reconcile_user`), and `:1992` (`move_note`). Comments in `imap.rs:98,167,223` also name product-specific wrapper and date behavior. ## 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 recovery, reconciliation, note movement, and IMAP byte-revision invariants. Describe wrapper bytes and date evidence in protocol terms. Keep mutation and merge behavior unchanged. ## Test idea Review comments against existing Notes, IMAP, DAV, and recovery tests. Run a source scan for product names. Do not change merge or status 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:57:03 +00:00

Author

Owner

Fixed the Rust comment findings in crates/plugins/notes. Explain replay recovery and identity-preserving note transitions. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: f10307aef9e2f8ba0dd55e7e64350a149dd96a97.

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/plugins/notes/src/imap.rs
crates/plugins/notes/src/lib.rs
crates/plugins/notes/src/store.rs
crates/plugins/notes/src/tasks_dav.rs
crates/plugins/notes/src/tasks_store.rs
crates/plugins/notes/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/plugins/notes`. Explain replay recovery and identity-preserving note transitions. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `f10307aef9e2f8ba0dd55e7e64350a149dd96a97`. 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/plugins/notes/src/imap.rs` - `crates/plugins/notes/src/lib.rs` - `crates/plugins/notes/src/store.rs` - `crates/plugins/notes/src/tasks_dav.rs` - `crates/plugins/notes/src/tasks_store.rs` - `crates/plugins/notes/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:41 +00:00

Author

Owner

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

docs: explain replay recovery and identity-preserving Note transitions (#932)

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/plugins/notes/src/imap.rs
crates/plugins/notes/src/lib.rs
crates/plugins/notes/src/store.rs
crates/plugins/notes/src/tasks_dav.rs
crates/plugins/notes/src/tasks_store.rs
crates/plugins/notes/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: `580668848f4eab8f8d93fd3d18376f29822f3485`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: explain replay recovery and identity-preserving Note transitions (#932) 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/plugins/notes/src/imap.rs` - `crates/plugins/notes/src/lib.rs` - `crates/plugins/notes/src/store.rs` - `crates/plugins/notes/src/tasks_dav.rs` - `crates/plugins/notes/src/tasks_store.rs` - `crates/plugins/notes/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: explain replay recovery and identity-preserving Note transitions (#932)

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