13 files changed, 125 insertions, 60 deletions
diff --git a/include/zix/allocator.h b/include/zix/allocator.h
index 34ee091..97aa71c 100644
--- a/include/zix/allocator.h
+++ b/include/zix/allocator.h
@@ -12,7 +12,7 @@ ZIX_BEGIN_DECLS
 
 /**
    @defgroup zix_allocator Allocator
-   @ingroup zix
+   @ingroup zix_allocation
    @{
 */
 
diff --git a/include/zix/attributes.h b/include/zix/attributes.h
index 9a25f9c..1fe1183 100644
--- a/include/zix/attributes.h
+++ b/include/zix/attributes.h
@@ -6,7 +6,7 @@
 
 /**
    @defgroup zix_attributes Attributes
-   @ingroup zix
+   @ingroup zix_utilities
    @{
 */
 
diff --git a/include/zix/bitset.h b/include/zix/bitset.h
index dcb1b93..96816c8 100644
--- a/include/zix/bitset.h
+++ b/include/zix/bitset.h
@@ -13,7 +13,7 @@
 
 /**
    @defgroup zix_bitset Bitset
-   @ingroup zix
+   @ingroup zix_data_structures
    @{
 */
 
diff --git a/include/zix/btree.h b/include/zix/btree.h
index 0658be8..7199dbc 100644
--- a/include/zix/btree.h
+++ b/include/zix/btree.h
@@ -17,7 +17,7 @@ ZIX_BEGIN_DECLS
 
 /**
    @defgroup zix_btree BTree
-   @ingroup zix
+   @ingroup zix_data_structures
    @{
 */
 
diff --git a/include/zix/bump_allocator.h b/include/zix/bump_allocator.h
index bec45c8..c054207 100644
--- a/include/zix/bump_allocator.h
+++ b/include/zix/bump_allocator.h
@@ -10,6 +10,12 @@
 #include <stddef.h>
 
 /**
+   @defgroup bump_allocator Bump Allocator
+   @ingroup zix_allocation
+   @{
+*/
+
+/**
    A simple bump-pointer allocator that never frees.
 
    This is about the simplest possible allocator that is useful in practice.
@@ -50,4 +56,8 @@ ZIX_API
 ZixBumpAllocator
 zix_bump_allocator(size_t capacity, void* ZIX_NONNULL buffer);
 
+/**
+   @}
+*/
+
 #endif // ZIX_BUMP_ALLOCATOR_H
diff --git a/include/zix/digest.h b/include/zix/digest.h
index 4c15444..4c4fb02 100644
--- a/include/zix/digest.h
+++ b/include/zix/digest.h
@@ -13,7 +13,7 @@ ZIX_BEGIN_DECLS
 
 /**
    @defgroup zix_digest Digest
-   @ingroup zix
+   @ingroup zix_utilities
 
    Functions to generate a short "digest" of data with minimal collisions.
 
diff --git a/include/zix/hash.h b/include/zix/hash.h
index a5492a6..026662c 100644
--- a/include/zix/hash.h
+++ b/include/zix/hash.h
@@ -15,7 +15,7 @@ ZIX_BEGIN_DECLS
 
 /**
    @defgroup zix_hash Hash
-   @ingroup zix
+   @ingroup zix_data_structures
    @{
 */
 
diff --git a/include/zix/ring.h b/include/zix/ring.h
index ec255a4..17a0e13 100644
--- a/include/zix/ring.h
+++ b/include/zix/ring.h
@@ -14,7 +14,12 @@ ZIX_BEGIN_DECLS
 
 /**
    @defgroup zix_ring Ring
-   @ingroup zix
+   @ingroup zix_data_structures
+   @{
+*/
+
+/**
+   @defgroup zix_ring_definition Definition
    @{
 */
 
@@ -27,20 +32,6 @@ ZIX_BEGIN_DECLS
 typedef struct ZixRingImpl ZixRing;
 
 /**
-   A transaction for writing data in multiple parts.
-
-   The simple zix_ring_write() can be used to write an atomic message that will
-   immediately be visible to the reader, but transactions allow data to be
-   written in several chunks before being "committed" and becoming readable.
-   This can be useful for things like prefixing messages with a header without
-   needing an allocated buffer to construct the "packet".
-*/
-typedef struct {
-  uint32_t read_head;  ///< Read head at the start of the transaction
-  uint32_t write_head; ///< Write head if the transaction were committed
-} ZixRingTransaction;
-
-/**
    Create a new ring.
 
    @param allocator Allocator for the ring.
@@ -79,24 +70,6 @@ void
 zix_ring_reset(ZixRing* ZIX_NONNULL ring);
 
 /**
-   Return the number of bytes of space available for reading.
-
-   Reader only.
-*/
-ZIX_PURE_API
-uint32_t
-zix_ring_read_space(const ZixRing* ZIX_NONNULL ring);
-
-/**
-   Return the number of bytes of space available for writing.
-
-   Writer only.
-*/
-ZIX_PURE_API
-uint32_t
-zix_ring_write_space(const ZixRing* ZIX_NONNULL ring);
-
-/**
    Return the capacity (the total write space when empty).
 
    This function returns a constant for any given ring, and may (but usually
@@ -107,37 +80,59 @@ uint32_t
 zix_ring_capacity(const ZixRing* ZIX_NONNULL ring);
 
 /**
-   Read from the ring without advancing the read head.
-
-   Reader only.
+   @}
+   @defgroup zix_ring_read Reading
+   Functions that may only be called by the read thread.
+   @{
 */
+
+/// Return the number of bytes available for reading
+ZIX_PURE_API
+uint32_t
+zix_ring_read_space(const ZixRing* ZIX_NONNULL ring);
+
+/// Read from the ring without advancing the read head
 ZIX_API
 uint32_t
 zix_ring_peek(ZixRing* ZIX_NONNULL ring, void* ZIX_NONNULL dst, uint32_t size);
 
-/**
-   Read from the ring and advance the read head.
-
-   Reader only.
-*/
+/// Read from the ring and advance the read head
 ZIX_API
 uint32_t
 zix_ring_read(ZixRing* ZIX_NONNULL ring, void* ZIX_NONNULL dst, uint32_t size);
 
-/**
-   Skip data in the ring (advance read head without reading).
-
-   Reader only.
-*/
+/// Advance the read head, ignoring any data
 ZIX_API
 uint32_t
 zix_ring_skip(ZixRing* ZIX_NONNULL ring, uint32_t size);
 
 /**
-   Write data to the ring.
+   @}
+   @defgroup zix_ring_write Writing
+   Functions that may only be called by the write thread.
+   @{
+*/
 
-   Writer only.
+/**
+   A transaction for writing data in multiple parts.
+
+   The simple zix_ring_write() can be used to write an atomic message that will
+   immediately be visible to the reader, but transactions allow data to be
+   written in several chunks before being "committed" and becoming readable.
+   This can be useful for things like prefixing messages with a header without
+   needing an allocated buffer to construct the "packet".
 */
+typedef struct {
+  uint32_t read_head;  ///< Read head at the start of the transaction
+  uint32_t write_head; ///< Write head if the transaction were committed
+} ZixRingTransaction;
+
+/// Return the number of bytes available for writing
+ZIX_PURE_API
+uint32_t
+zix_ring_write_space(const ZixRing* ZIX_NONNULL ring);
+
+/// Write data to the ring
 ZIX_API
 uint32_t
 zix_ring_write(ZixRing* ZIX_NONNULL    ring,
@@ -204,6 +199,7 @@ zix_ring_commit_write(ZixRing* ZIX_NONNULL                  ring,
 
 /**
    @}
+   @}
 */
 
 ZIX_END_DECLS
diff --git a/include/zix/sem.h b/include/zix/sem.h
index b22dfdd..ea993fb 100644
--- a/include/zix/sem.h
+++ b/include/zix/sem.h
@@ -21,7 +21,7 @@ ZIX_BEGIN_DECLS
 
 /**
    @defgroup zix_sem Semaphore
-   @ingroup zix
+   @ingroup zix_threading
    @{
 */
 
diff --git a/include/zix/status.h b/include/zix/status.h
index 906b812..0e95f43 100644
--- a/include/zix/status.h
+++ b/include/zix/status.h
@@ -9,9 +9,8 @@
 ZIX_BEGIN_DECLS
 
 /**
-   @defgroup zix Zix C API
-   @{
    @defgroup zix_status Status Codes
+   @ingroup zix_utilities
    @{
 */
 
@@ -38,7 +37,6 @@ zix_strerror(ZixStatus status);
 
 /**
    @}
-   @}
 */
 
 ZIX_END_DECLS
diff --git a/include/zix/thread.h b/include/zix/thread.h
index 3ba4702..d3b5021 100644
--- a/include/zix/thread.h
+++ b/include/zix/thread.h
@@ -19,7 +19,7 @@ ZIX_BEGIN_DECLS
 
 /**
    @defgroup zix_thread Thread
-   @ingroup zix
+   @ingroup zix_threading
    @{
 */
 
diff --git a/include/zix/tree.h b/include/zix/tree.h
index 919cba9..939385b 100644
--- a/include/zix/tree.h
+++ b/include/zix/tree.h
@@ -16,7 +16,7 @@ ZIX_BEGIN_DECLS
 
 /**
    @defgroup zix_tree Tree
-   @ingroup zix
+   @ingroup zix_data_structures
    @{
 */
 
diff --git a/include/zix/zix.h b/include/zix/zix.h
new file mode 100644
index 0000000..02ab31f
--- /dev/null
+++ b/include/zix/zix.h
@@ -0,0 +1,61 @@
+// Copyright 2016-2022 David Robillard <d@drobilla.net>
+// SPDX-License-Identifier: ISC
+
+#ifndef ZIX_ZIX_H
+#define ZIX_ZIX_H
+
+// IWYU pragma: begin_exports
+
+/**
+   @defgroup zix Zix C API
+   @{
+*/
+
+/**
+   @defgroup zix_utilities Utilities
+   @{
+*/
+
+#include "zix/attributes.h"
+#include "zix/digest.h"
+#include "zix/function_types.h"
+#include "zix/status.h"
+
+/**
+   @}
+   @defgroup zix_allocation Allocation
+   @{
+*/
+
+#include "zix/allocator.h"
+#include "zix/bump_allocator.h"
+
+/**
+   @}
+   @defgroup zix_data_structures Data Structures
+   @{
+*/
+
+#include "zix/bitset.h"
+#include "zix/btree.h"
+#include "zix/hash.h"
+#include "zix/ring.h"
+#include "zix/tree.h"
+
+/**
+   @}
+   @defgroup zix_threading Threading
+   @{
+*/
+
+#include "zix/sem.h"
+#include "zix/thread.h"
+
+/**
+   @}
+   @}
+*/
+
+// IWYU pragma: end_exports
+
+#endif /* ZIX_ZIX_H */