kayg/calternal

Watch

Fork 0

DOCS: document filesystem operations and remove product names #909

New issue

Open

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

kayg commented

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

Owner

Evidence

At the #863 audit base, a case-sensitive scan found 4 comment lines in 2 files under crates/calternal-fs/src that name common third-party products. Examples: sidecar.rs:18-20 names Apple Photos; versions.rs:5 says “Nextcloud-style”.
The public-function scan found 21 functions without adjacent docs. Non-obvious examples include file_ops.rs:27 (move_path), :117 (copy), :205 (delete), trash.rs:120 (restore), and root.rs:940 (list_page). These operations move version history, restore from trash, and use paged directory results.

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 path, overwrite, trash, version-tree, pagination, and read-only-copy invariants. Name sidecar extensions and retention behavior without vendor names. Keep all filesystem access directory-handle-relative and preserve implementation behavior.

Test idea

Review function comments against existing filesystem tests. Run a source scan for product names. Do not change existing security or error expectations.

## Evidence At the #863 audit base, a case-sensitive scan found 4 comment lines in 2 files under `crates/calternal-fs/src` that name common third-party products. Examples: `sidecar.rs:18-20` names Apple Photos; `versions.rs:5` says “Nextcloud-style”. The public-function scan found 21 functions without adjacent docs. Non-obvious examples include `file_ops.rs:27` (`move_path`), `:117` (`copy`), `:205` (`delete`), `trash.rs:120` (`restore`), and `root.rs:940` (`list_page`). These operations move version history, restore from trash, and use paged directory results. ## 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 path, overwrite, trash, version-tree, pagination, and read-only-copy invariants. Name sidecar extensions and retention behavior without vendor names. Keep all filesystem access directory-handle-relative and preserve implementation behavior. ## Test idea Review function comments against existing filesystem tests. Run a source scan for product names. Do not change existing security or error 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:50:21 +00:00

Author

Owner

Fixed the Rust comment findings in crates/calternal-fs. Document content and version operations and directory cursors. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: adb9eae333f83de9122e5a3b0a1446105b993f66.

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-fs/src/file_ops.rs
crates/calternal-fs/src/root.rs
crates/calternal-fs/src/sidecar.rs
crates/calternal-fs/src/trash.rs
crates/calternal-fs/src/versions.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-fs`. Document content and version operations and directory cursors. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `adb9eae333f83de9122e5a3b0a1446105b993f66`. 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-fs/src/file_ops.rs` - `crates/calternal-fs/src/root.rs` - `crates/calternal-fs/src/sidecar.rs` - `crates/calternal-fs/src/trash.rs` - `crates/calternal-fs/src/versions.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:30 +00:00

Author

Owner

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

docs: document content and Version operations and directory cursors (#909)

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-fs/src/file_ops.rs
crates/calternal-fs/src/root.rs
crates/calternal-fs/src/sidecar.rs
crates/calternal-fs/src/trash.rs
crates/calternal-fs/src/versions.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: `9a2a2b0b08262f3fada91d9c60edda349a9ab461`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: document content and Version operations and directory cursors (#909) 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-fs/src/file_ops.rs` - `crates/calternal-fs/src/root.rs` - `crates/calternal-fs/src/sidecar.rs` - `crates/calternal-fs/src/trash.rs` - `crates/calternal-fs/src/versions.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 content and Version operations and directory cursors (#909)

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

No description provided.

Rows
Columns