From a74e23aa4ffcd022f8d3dcd6e6e3cba3e0047fb6 Mon Sep 17 00:00:00 2001 From: "Jeffrey C. Ollie" Date: Sat, 29 Aug 2026 20:21:23 -0500 Subject: [PATCH] expand the module-level doc comments Each library file now documents what its type represents, how it is obtained, its key operations, and the ownership rules. The root module doc gives an overview of the API, the error model, and the ownership model, since it is the landing page of the generated docs. Query, enums, and error previously had no module doc at all. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_017i7R7ReKJAHGQpitxGXqrb --- src/Database.zig | 9 ++++++++- src/Directory.zig | 8 +++++++- src/FilenamesIterator.zig | 8 ++++++-- src/IndexOpts.zig | 6 +++++- src/Message.zig | 9 ++++++++- src/MessagesIterator.zig | 9 +++++++-- src/PairsIterator.zig | 5 ++++- src/PropertiesIterator.zig | 5 ++++- src/Query.zig | 7 +++++++ src/TagsIterator.zig | 7 ++++++- src/Thread.zig | 8 +++++++- src/ValuesIterator.zig | 6 +++++- src/enums.zig | 6 ++++++ src/error.zig | 5 +++++ src/notmuch.zig | 15 ++++++++++++++- 15 files changed, 99 insertions(+), 14 deletions(-) diff --git a/src/Database.zig b/src/Database.zig index 87cc78a..e4c30de 100644 --- a/src/Database.zig +++ b/src/Database.zig @@ -1,7 +1,14 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! Zig wrapper around the `notmuch` database APIs. +//! An open notmuch database. +//! +//! Obtain one with `open` or `create`; both return a tagged union carrying +//! either the database or an error along with libnotmuch's human-readable +//! message. A database supports searching via `queryCreate`, indexing and +//! removing mail files, message lookup by ID or filename, atomic sections, +//! configuration access, and maintenance operations such as `upgrade` and +//! `compact`. Call `deinit` to close and free the database when finished. const Database = @This(); diff --git a/src/Directory.zig b/src/Directory.zig index 9bee2e8..a051339 100644 --- a/src/Directory.zig +++ b/src/Directory.zig @@ -1,7 +1,13 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! Zig wrapper around the `notmuch` directory APIs. +//! A directory entry in the notmuch database, obtained from +//! `Database.getDirectory`. +//! +//! Stores a directory modification time (`getMtime`/`setMtime`) so callers +//! can efficiently detect new mail, and lists the database's knowledge of the +//! directory's contents via `getChildFiles` and `getChildDirectories`. The +//! directory object is owned by the database; `deinit` releases it sooner. const Directory = @This(); const std = @import("std"); diff --git a/src/FilenamesIterator.zig b/src/FilenamesIterator.zig index c8afc06..1961ab1 100644 --- a/src/FilenamesIterator.zig +++ b/src/FilenamesIterator.zig @@ -1,8 +1,12 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! A Zig wrapper around the `notmuch` C APIs for dealing with -//! lists of filenames. +//! Iterator over a list of filenames, as returned by `Message.getFilenames` +//! and the `Directory` child listings. +//! +//! The strings returned by `next` are owned by the iterator's parent object. +//! The iterator itself is owned by the object it came from; `deinit` releases +//! it sooner. pub const FilenamesIterator = @This(); const std = @import("std"); diff --git a/src/IndexOpts.zig b/src/IndexOpts.zig index 36eb67b..7d33324 100644 --- a/src/IndexOpts.zig +++ b/src/IndexOpts.zig @@ -1,7 +1,11 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! Zig wrapper around the `notmuch` C APIs that deal with index options. +//! Message indexing options, obtained from `Database.getDefaultIndexOpts` +//! and passed to `Database.indexFile` and `Message.reindex`. +//! +//! Currently the only option is the decryption policy +//! (`setDecryptPolicy`/`getDecryptPolicy`). const IndexOpts = @This(); const std = @import("std"); diff --git a/src/Message.zig b/src/Message.zig index be79187..631f48f 100644 --- a/src/Message.zig +++ b/src/Message.zig @@ -1,7 +1,14 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! Zig wrapper around the `notmuch` C APIs that deal with messages. +//! A single email message in the notmuch database. +//! +//! Obtained from searches (`Query.searchMessages`), lookups +//! (`Database.findMessage`), thread traversal, or indexing. Exposes the +//! message's identity, headers, dates, and filenames, and supports mutating +//! tags and properties, synchronizing maildir flags, and batching tag changes +//! with `freeze`/`thaw`. The message is owned by the query or database it +//! came from; `deinit` releases it sooner. const Message = @This(); const std = @import("std"); diff --git a/src/MessagesIterator.zig b/src/MessagesIterator.zig index 8212e3b..bd85d32 100644 --- a/src/MessagesIterator.zig +++ b/src/MessagesIterator.zig @@ -1,8 +1,13 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! A Zig wrapper around the `notmuch` C APIs for dealing with -//! lists of messages. +//! Iterator over a list of messages, as returned by `Query.searchMessages`, +//! `Thread.getMessages`, and `Message.getReplies`. +//! +//! `next` returns `Message` objects owned by the underlying query; +//! `collectTags` gathers the tags of all remaining messages instead. The +//! iterator is owned by the query it derived from; `deinit` releases it +//! sooner. const MessagesIterator = @This(); const c = @import("c"); diff --git a/src/PairsIterator.zig b/src/PairsIterator.zig index 66aac94..684bcb8 100644 --- a/src/PairsIterator.zig +++ b/src/PairsIterator.zig @@ -1,7 +1,10 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! Zig wrapper around the `notmuch` C APIs that deal with config pair lists. +//! Iterator over (key, value) configuration pairs, as returned by +//! `Database.configGetPairs`. +//! +//! The strings returned by `next` live only as long as the iterator. pub const PairsIterator = @This(); const std = @import("std"); diff --git a/src/PropertiesIterator.zig b/src/PropertiesIterator.zig index a189866..aab8396 100644 --- a/src/PropertiesIterator.zig +++ b/src/PropertiesIterator.zig @@ -1,7 +1,10 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! Zig wrapper around the `notmuch` C APIs that deal with property lists. +//! Iterator over the (key, value) properties of a message, as returned by +//! `Message.getProperties`. +//! +//! Owned by the message it came from and valid only as long as the message. const PropertiesIterator = @This(); const std = @import("std"); diff --git a/src/Query.zig b/src/Query.zig index eeaa924..9fe17dc 100644 --- a/src/Query.zig +++ b/src/Query.zig @@ -1,6 +1,13 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later +//! A search of the notmuch database, created with `Database.queryCreate` or +//! `Database.queryCreateWithSyntax`. +//! +//! Configure the search with `setSort`, `setOmitExcluded`, and +//! `addTagExclude`, then run it with `searchMessages` or `searchThreads`, or +//! count the results with `countMessages` and `countThreads`. Everything a +//! query returns is owned by the query and freed by `deinit`. const Query = @This(); const std = @import("std"); diff --git a/src/TagsIterator.zig b/src/TagsIterator.zig index ceeb924..1c2086c 100644 --- a/src/TagsIterator.zig +++ b/src/TagsIterator.zig @@ -1,7 +1,12 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! Iterator over `notmuch` tags. +//! Iterator over a list of tags, as returned by `Message.getTags`, +//! `Thread.getTags`, `Database.getAllTags`, and +//! `MessagesIterator.collectTags`. +//! +//! The iterator is owned by the object it came from; `deinit` releases it +//! sooner. const TagsIterator = @This(); const std = @import("std"); diff --git a/src/Thread.zig b/src/Thread.zig index 490c7ca..0cb732e 100644 --- a/src/Thread.zig +++ b/src/Thread.zig @@ -1,7 +1,13 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! Zig wrapper around `notmuch` message thread APIs. +//! A thread of messages matching a search, as returned by +//! `Query.searchThreads`. +//! +//! Exposes the thread's subject, authors, dates, and message and file +//! counts, plus traversal of its messages via `getToplevelMessages` and +//! `getMessages`. The thread is owned by the query it derived from; `deinit` +//! releases it sooner. const Thread = @This(); const std = @import("std"); diff --git a/src/ValuesIterator.zig b/src/ValuesIterator.zig index 17843c1..68ed058 100644 --- a/src/ValuesIterator.zig +++ b/src/ValuesIterator.zig @@ -1,7 +1,11 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! Zig wrapper around the `notmuch` C APIs that deal with value lists. +//! Iterator over a `;`-delimited list of configuration values, as returned +//! by `Database.configGetValues` and `Database.configGetValuesString`. +//! +//! The strings returned by `next` live only as long as the iterator; `start` +//! resets iteration to the first value. pub const ValuesIterator = @This(); const std = @import("std"); diff --git a/src/enums.zig b/src/enums.zig index 7c62371..7e0f6ce 100644 --- a/src/enums.zig +++ b/src/enums.zig @@ -1,6 +1,12 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later +//! Zig enums mirroring the C enumerations in `notmuch.h`. +//! +//! Each enum takes its values directly from the C constants and is checked +//! against the header at compile time, so building against a libnotmuch whose +//! enumerations have changed fails the build instead of misbehaving at +//! runtime. const std = @import("std"); const c = @import("c"); diff --git a/src/error.zig b/src/error.zig index b53395f..59b5ce5 100644 --- a/src/error.zig +++ b/src/error.zig @@ -1,6 +1,11 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later +//! The `Error` set covering every `notmuch_status_t` code, and `wrap`, which +//! converts a C status return into a Zig error union. +//! +//! Wrappers with narrowed error sets instead convert the codes they document +//! individually and map anything undocumented to `error.Unexpected`. const std = @import("std"); const c = @import("c"); diff --git a/src/notmuch.zig b/src/notmuch.zig index 0566117..cf12c89 100644 --- a/src/notmuch.zig +++ b/src/notmuch.zig @@ -1,8 +1,21 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: GPL-3.0-or-later -//! Zig bindings for the Notmuch C API. +//! Zig bindings for the notmuch mail indexer's C library, `libnotmuch`. //! +//! Start with `Database.open` or `Database.create` to get a `Database`, then +//! create a `Query` with `Database.queryCreate` to search for `Message` and +//! `Thread` objects. Search results come back as iterators +//! (`MessagesIterator`, `ThreadsIterator`, and friends) with a `next` method. +//! +//! `notmuch_status_t` return codes are translated into Zig error sets, +//! narrowed per function to the codes that call can actually return; the full +//! set is `Error`. A status a function is not documented to return maps to +//! `error.Unexpected`. +//! +//! Objects returned from a query — messages, threads, tags, filenames — are +//! owned by the object they came from and are freed along with it; their +//! `deinit` methods merely release memory sooner. const std = @import("std"); const c = @import("c"); -- 2.51.2