kayg/calternal

Watch

Fork 0

DOCS: document Notes core modules and public helpers #917

New issue

Open

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

kayg commented

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

Owner

Evidence

At the #863 audit base, crates/calternal-notes-core/src/tasks/mod.rs:1 has no module comment.
A case-sensitive scan found 71 comment lines in 12 files that name common third-party products. Examples: tasks/model.rs:102 and markdown.rs:3.
The public-function scan found 16 functions without adjacent docs. Non-obvious examples include notes_index.rs:239 (link_rows_from_index), :302 (escape_angle_link_target), and composer.rs:122 (into_log_entry).

Owner rule

Comments are documentation. Each module and each non-obvious function needs a short, current comment. Source comments must not name third-party products.

Expected behaviour

Explain the Tasks module and its re-export boundary. Document link-index conversion, link escaping, and Composer conversion invariants. Replace product names with Markdown syntax or behavior descriptions. Keep parser and model behavior unchanged.

Test idea

Run a source scan for module/function comments and product names. Review comments against the existing Notes core tests. Do not change parser expectations.

## Evidence At the #863 audit base, `crates/calternal-notes-core/src/tasks/mod.rs:1` has no module comment. A case-sensitive scan found 71 comment lines in 12 files that name common third-party products. Examples: `tasks/model.rs:102` and `markdown.rs:3`. The public-function scan found 16 functions without adjacent docs. Non-obvious examples include `notes_index.rs:239` (`link_rows_from_index`), `:302` (`escape_angle_link_target`), and `composer.rs:122` (`into_log_entry`). ## Owner rule Comments are documentation. Each module and each non-obvious function needs a short, current comment. Source comments must not name third-party products. ## Expected behaviour Explain the Tasks module and its re-export boundary. Document link-index conversion, link escaping, and Composer conversion invariants. Replace product names with Markdown syntax or behavior descriptions. Keep parser and model behavior unchanged. ## Test idea Run a source scan for module/function comments and product names. Review comments against the existing Notes core tests. Do not change parser 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:52:41 +00:00

Author

Owner

Fixed the Rust comment findings in crates/calternal-notes-core. Document task exports and note link and composer conversions. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: 941d14fd50f56a71749ae79482d1928561985803.

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-notes-core/src/composer.rs
crates/calternal-notes-core/src/lib.rs
crates/calternal-notes-core/src/markdown.rs
crates/calternal-notes-core/src/nlp/classifier.rs
crates/calternal-notes-core/src/nlp/mod.rs
crates/calternal-notes-core/src/nlp/recognizers.rs
crates/calternal-notes-core/src/nlp/task_types.rs
crates/calternal-notes-core/src/nlp/tasks_recurrence_md.rs
crates/calternal-notes-core/src/nlp/tasks_sigils.rs
crates/calternal-notes-core/src/nlp/tests.rs
crates/calternal-notes-core/src/notes_index.rs
crates/calternal-notes-core/src/tasks/extract.rs
crates/calternal-notes-core/src/tasks/line.rs
crates/calternal-notes-core/src/tasks/mod.rs
crates/calternal-notes-core/src/tasks/model.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-notes-core`. Document task exports and note link and composer conversions. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `941d14fd50f56a71749ae79482d1928561985803`. 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-notes-core/src/composer.rs` - `crates/calternal-notes-core/src/lib.rs` - `crates/calternal-notes-core/src/markdown.rs` - `crates/calternal-notes-core/src/nlp/classifier.rs` - `crates/calternal-notes-core/src/nlp/mod.rs` - `crates/calternal-notes-core/src/nlp/recognizers.rs` - `crates/calternal-notes-core/src/nlp/task_types.rs` - `crates/calternal-notes-core/src/nlp/tasks_recurrence_md.rs` - `crates/calternal-notes-core/src/nlp/tasks_sigils.rs` - `crates/calternal-notes-core/src/nlp/tests.rs` - `crates/calternal-notes-core/src/notes_index.rs` - `crates/calternal-notes-core/src/tasks/extract.rs` - `crates/calternal-notes-core/src/tasks/line.rs` - `crates/calternal-notes-core/src/tasks/mod.rs` - `crates/calternal-notes-core/src/tasks/model.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: document Task exports and Note link and Composer conversions (#917)

kayg commented

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

Author

Owner

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

docs: document Task exports and Note link and Composer conversions (#917)

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-notes-core/src/composer.rs
crates/calternal-notes-core/src/lib.rs
crates/calternal-notes-core/src/markdown.rs
crates/calternal-notes-core/src/nlp/classifier.rs
crates/calternal-notes-core/src/nlp/mod.rs
crates/calternal-notes-core/src/nlp/recognizers.rs
crates/calternal-notes-core/src/nlp/task_types.rs
crates/calternal-notes-core/src/nlp/tasks_recurrence_md.rs
crates/calternal-notes-core/src/nlp/tasks_sigils.rs
crates/calternal-notes-core/src/nlp/tests.rs
crates/calternal-notes-core/src/notes_index.rs
crates/calternal-notes-core/src/tasks/extract.rs
crates/calternal-notes-core/src/tasks/line.rs
crates/calternal-notes-core/src/tasks/mod.rs
crates/calternal-notes-core/src/tasks/model.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: `3335ab5fd028c12f4d66657cadfaad1f5e890ad7`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: document Task exports and Note link and Composer conversions (#917) 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-notes-core/src/composer.rs` - `crates/calternal-notes-core/src/lib.rs` - `crates/calternal-notes-core/src/markdown.rs` - `crates/calternal-notes-core/src/nlp/classifier.rs` - `crates/calternal-notes-core/src/nlp/mod.rs` - `crates/calternal-notes-core/src/nlp/recognizers.rs` - `crates/calternal-notes-core/src/nlp/task_types.rs` - `crates/calternal-notes-core/src/nlp/tasks_recurrence_md.rs` - `crates/calternal-notes-core/src/nlp/tasks_sigils.rs` - `crates/calternal-notes-core/src/nlp/tests.rs` - `crates/calternal-notes-core/src/notes_index.rs` - `crates/calternal-notes-core/src/tasks/extract.rs` - `crates/calternal-notes-core/src/tasks/line.rs` - `crates/calternal-notes-core/src/tasks/mod.rs` - `crates/calternal-notes-core/src/tasks/model.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 Task exports and Note link and Composer conversions (#917)

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

No description provided.

Rows
Columns