kayg/calternal

Watch

Fork 0

DOCS: explain search index APIs #911

New issue

Open

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

kayg commented

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

Owner

Evidence

At the #863 audit base, the public-function scan found seven undocumented public functions in crates/calternal-search/src. Examples are index.rs:189 (document), :209 (log_document), :308 (open), and :423 (query_index). Their field mapping and index lifecycle behavior are not clear from the signatures alone.

Owner rule

Comments are documentation. Each non-obvious function needs a short, current comment.

Expected behaviour

Explain which fields each document builder indexes and the lifecycle and ownership rules for opening and querying the Index. Keep query and indexing behavior unchanged.

Test idea

Review comments against the existing search index tests. Do not change ranking, field, or error expectations.

## Evidence At the #863 audit base, the public-function scan found seven undocumented public functions in `crates/calternal-search/src`. Examples are `index.rs:189` (`document`), `:209` (`log_document`), `:308` (`open`), and `:423` (`query_index`). Their field mapping and index lifecycle behavior are not clear from the signatures alone. ## Owner rule Comments are documentation. Each non-obvious function needs a short, current comment. ## Expected behaviour Explain which fields each document builder indexes and the lifecycle and ownership rules for opening and querying the Index. Keep query and indexing behavior unchanged. ## Test idea Review comments against the existing search index tests. Do not change ranking, field, 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:51:38 +00:00

Author

Owner

Fixed the Rust comment findings in crates/calternal-search. Explain field mapping and index generation ownership. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: 2a6060c35cdb2ead7b0672925ef567f4ddddbc84.

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-search/src/index.rs
crates/calternal-search/src/plugin.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-search`. Explain field mapping and index generation ownership. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `2a6060c35cdb2ead7b0672925ef567f4ddddbc84`. 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-search/src/index.rs` - `crates/calternal-search/src/plugin.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:32 +00:00

Author

Owner

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

docs: explain field mapping and Index generation ownership (#911)

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-search/src/index.rs
crates/calternal-search/src/plugin.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: `beb218e832a3e48df3c904b59597f9dfab9ef222`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: explain field mapping and Index generation ownership (#911) 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-search/src/index.rs` - `crates/calternal-search/src/plugin.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 field mapping and Index generation ownership (#911)

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

No description provided.

Rows
Columns