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");