Fix doc comments

11 files changed, 64 insertions, 62 deletions

diff --git a/include/zix/allocator.h b/include/zix/allocator.h
index bcffda5..7a4f5ee 100644
--- a/include/zix/allocator.h
+++ b/include/zix/allocator.h
@@ -1,4 +1,4 @@
-// Copyright 2021 David Robillard <d@drobilla.net>
+// Copyright 2021-2022 David Robillard <d@drobilla.net>
 // SPDX-License-Identifier: ISC
 
 #ifndef ZIX_ALLOCATOR_H
@@ -13,9 +13,8 @@ extern "C" {
 #endif
 
 /**
-   @addtogroup zix
-   @{
-   @name Allocator
+   @defgroup zix_allocator Allocator
+   @ingroup zix
    @{
 */
 
@@ -176,7 +175,6 @@ zix_aligned_free(ZixAllocator* const ZIX_NULLABLE allocator,
 
 /**
    @}
-   @}
 */
 
 #ifdef __cplusplus
diff --git a/include/zix/attributes.h b/include/zix/attributes.h
index 602fac8..7c352d2 100644
--- a/include/zix/attributes.h
+++ b/include/zix/attributes.h
@@ -1,11 +1,12 @@
-// Copyright 2021 David Robillard <d@drobilla.net>
+// Copyright 2021-2022 David Robillard <d@drobilla.net>
 // SPDX-License-Identifier: ISC
 
 #ifndef ZIX_ATTRIBUTES_H
 #define ZIX_ATTRIBUTES_H
 
 /**
-   @addtogroup zix
+   @defgroup zix_attributes Attributes
+   @ingroup zix
    @{
 */
 
diff --git a/include/zix/bitset.h b/include/zix/bitset.h
index 38d612e..9b4dc89 100644
--- a/include/zix/bitset.h
+++ b/include/zix/bitset.h
@@ -1,4 +1,4 @@
-// Copyright 2014-2020 David Robillard <d@drobilla.net>
+// Copyright 2014-2022 David Robillard <d@drobilla.net>
 // SPDX-License-Identifier: ISC
 
 #ifndef ZIX_BITSET_H
@@ -12,9 +12,8 @@
 #include <stdint.h>
 
 /**
-   @addtogroup zix
-   @{
-   @name Bitset
+   @defgroup zix_bitset Bitset
+   @ingroup zix
    @{
 */
 
@@ -77,7 +76,6 @@ zix_bitset_count_up_to_if(const ZixBitset* ZIX_NONNULL      b,
 
 /**
    @}
-   @}
 */
 
 #endif /* ZIX_BITSET_H */
diff --git a/include/zix/btree.h b/include/zix/btree.h
index 24a0171..1b36908 100644
--- a/include/zix/btree.h
+++ b/include/zix/btree.h
@@ -1,4 +1,4 @@
-// Copyright 2011-2020 David Robillard <d@drobilla.net>
+// Copyright 2011-2022 David Robillard <d@drobilla.net>
 // SPDX-License-Identifier: ISC
 
 #ifndef ZIX_BTREE_H
@@ -17,9 +17,8 @@ extern "C" {
 #endif
 
 /**
-   @addtogroup zix
-   @{
-   @name BTree
+   @defgroup zix_btree BTree
+   @ingroup zix
    @{
 */
 
@@ -81,8 +80,12 @@ zix_btree_new(ZixAllocator* ZIX_NULLABLE allocator,
 /**
    Free `t` and all the nodes it contains.
 
+   @param t The tree to free.
+
    @param destroy Function to call once for every value in the tree.  This can
    be used to free values if they are dynamically allocated.
+
+   @param destroy_user_data Opaque pointer to pass to `destroy`.
 */
 ZIX_API
 void
@@ -93,8 +96,12 @@ zix_btree_free(ZixBTree* ZIX_NULLABLE      t,
 /**
    Clear everything from `t`, leaving it empty.
 
+   @param t The tree to clear.
+
    @param destroy Function called exactly once for every value in the tree,
    just before that value is removed from the tree.
+
+   @param destroy_user_data Opaque pointer to pass to `destroy`.
 */
 ZIX_API
 void
@@ -203,7 +210,6 @@ zix_btree_iter_next(ZixBTreeIter iter);
 
 /**
    @}
-   @}
 */
 
 #ifdef __cplusplus
diff --git a/include/zix/common.h b/include/zix/common.h
index 59a61ac..5a71be5 100644
--- a/include/zix/common.h
+++ b/include/zix/common.h
@@ -1,4 +1,4 @@
-// Copyright 2016-2020 David Robillard <d@drobilla.net>
+// Copyright 2016-2022 David Robillard <d@drobilla.net>
 // SPDX-License-Identifier: ISC
 
 #ifndef ZIX_COMMON_H
@@ -9,7 +9,7 @@
 #include <stdbool.h>
 
 /**
-   @addtogroup zix
+   @defgroup zix Zix C API
    @{
 */
 
@@ -17,19 +17,20 @@
 extern "C" {
 #endif
 
+/// A status code returned by functions
 typedef enum {
-  ZIX_STATUS_SUCCESS,
-  ZIX_STATUS_ERROR,
-  ZIX_STATUS_NO_MEM,
-  ZIX_STATUS_NOT_FOUND,
-  ZIX_STATUS_EXISTS,
-  ZIX_STATUS_BAD_ARG,
-  ZIX_STATUS_BAD_PERMS,
-  ZIX_STATUS_REACHED_END,
-  ZIX_STATUS_TIMEOUT,
-  ZIX_STATUS_OVERFLOW,
-  ZIX_STATUS_NOT_SUPPORTED,
-  ZIX_STATUS_UNAVAILABLE,
+  ZIX_STATUS_SUCCESS,       ///< Success
+  ZIX_STATUS_ERROR,         ///< Unknown error
+  ZIX_STATUS_NO_MEM,        ///< Out of memory
+  ZIX_STATUS_NOT_FOUND,     ///< Not found
+  ZIX_STATUS_EXISTS,        ///< Exists
+  ZIX_STATUS_BAD_ARG,       ///< Bad argument
+  ZIX_STATUS_BAD_PERMS,     ///< Bad permissions
+  ZIX_STATUS_REACHED_END,   ///< Reached end
+  ZIX_STATUS_TIMEOUT,       ///< Timeout
+  ZIX_STATUS_OVERFLOW,      ///< Overflow
+  ZIX_STATUS_NOT_SUPPORTED, ///< Not supported
+  ZIX_STATUS_UNAVAILABLE,   ///< Resource unavailable
 } ZixStatus;
 
 /// Return a string describing a status code
diff --git a/include/zix/digest.h b/include/zix/digest.h
index 2becad2..5a0eb16 100644
--- a/include/zix/digest.h
+++ b/include/zix/digest.h
@@ -1,4 +1,4 @@
-// Copyright 2012-2021 David Robillard <d@drobilla.net>
+// Copyright 2012-2022 David Robillard <d@drobilla.net>
 // SPDX-License-Identifier: ISC
 
 #ifndef ZIX_DIGEST_H
@@ -14,14 +14,15 @@ extern "C" {
 #endif
 
 /**
-   @addtogroup zix
-   @{
-   @name Digest
+   @defgroup zix_digest Digest
+   @ingroup zix
+
    Functions to generate a short "digest" of data with minimal collisions.
 
    These are good general-purpose hash functions for indexing arbitrary data,
    but are not necessarily stable across platforms and should never be used for
    cryptographic purposes.
+
    @{
 */
 
@@ -89,6 +90,10 @@ ZIX_PURE_API
 size_t
 zix_digest_aligned(size_t seed, const void* ZIX_NONNULL buf, size_t len);
 
+/**
+   @}
+*/
+
 #ifdef __cplusplus
 } /* extern "C" */
 #endif
diff --git a/include/zix/hash.h b/include/zix/hash.h
index a0146de..c1521e0 100644
--- a/include/zix/hash.h
+++ b/include/zix/hash.h
@@ -1,4 +1,4 @@
-// Copyright 2011-2021 David Robillard <d@drobilla.net>
+// Copyright 2011-2022 David Robillard <d@drobilla.net>
 // SPDX-License-Identifier: ISC
 
 #ifndef ZIX_HASH_H
@@ -16,9 +16,8 @@ extern "C" {
 #endif
 
 /**
-   @addtogroup zix
-   @{
-   @name Hash
+   @defgroup zix_hash Hash
+   @ingroup zix
    @{
 */
 
@@ -115,6 +114,7 @@ typedef struct {
 /**
    Create a new hash table.
 
+   @param allocator Allocator used for the internal array.
    @param key_func A function to retrieve the key from a record.
    @param hash_func The key hashing function.
    @param equal_func A function to test keys for equality.
@@ -319,7 +319,6 @@ zix_hash_find_record(const ZixHash* ZIX_NONNULL    hash,
 
 /**
    @}
-   @}
 */
 
 #ifdef __cplusplus
diff --git a/include/zix/ring.h b/include/zix/ring.h
index 8100d2b..6fb78ac 100644
--- a/include/zix/ring.h
+++ b/include/zix/ring.h
@@ -15,9 +15,8 @@ extern "C" {
 #endif
 
 /**
-   @addtogroup zix
-   @{
-   @name Ring
+   @defgroup zix_ring Ring
+   @ingroup zix
    @{
 */
 
@@ -45,6 +44,8 @@ typedef struct {
 
 /**
    Create a new ring.
+
+   @param allocator Allocator for the ring.
    @param size Size in bytes (note this may be rounded up).
 
    At most `size` - 1 bytes may be stored in the ring at once.
@@ -205,7 +206,6 @@ zix_ring_commit_write(ZixRing* ZIX_NONNULL                  ring,
 
 /**
    @}
-   @}
 */
 
 #ifdef __cplusplus
diff --git a/include/zix/sem.h b/include/zix/sem.h
index 41b9860..e7db792 100644
--- a/include/zix/sem.h
+++ b/include/zix/sem.h
@@ -24,9 +24,8 @@ extern "C" {
 #include <time.h>
 
 /**
-   @addtogroup zix
-   @{
-   @name Semaphore
+   @defgroup zix_sem Semaphore
+   @ingroup zix
    @{
 */
 
@@ -148,7 +147,6 @@ struct ZixSemImpl {
 /**
    @endcond
    @}
-   @}
 */
 
 #ifdef __cplusplus
diff --git a/include/zix/thread.h b/include/zix/thread.h
index 482315a..173cc39 100644
--- a/include/zix/thread.h
+++ b/include/zix/thread.h
@@ -1,4 +1,4 @@
-// Copyright 2012-2020 David Robillard <d@drobilla.net>
+// Copyright 2012-2022 David Robillard <d@drobilla.net>
 // SPDX-License-Identifier: ISC
 
 #ifndef ZIX_THREAD_H
@@ -20,22 +20,21 @@ extern "C" {
 #endif
 
 /**
-   @addtogroup zix
-   @{
-   @name Thread
+   @defgroup zix_thread Thread
+   @ingroup zix
    @{
 */
 
 #ifdef _WIN32
-#  define ZIX_THREAD_RESULT 0
-#  define ZIX_THREAD_FUNC __stdcall
+#  define ZIX_THREAD_RESULT 0       ///< Result returned from a thread function
+#  define ZIX_THREAD_FUNC __stdcall ///< Thread function attribute
 
 typedef HANDLE ZixThread;
 typedef DWORD  ZixThreadResult;
 
 #else
-#  define ZIX_THREAD_RESULT NULL
-#  define ZIX_THREAD_FUNC
+#  define ZIX_THREAD_RESULT NULL ///< Result returned from a thread function
+#  define ZIX_THREAD_FUNC        ///< Thread function attribute
 
 typedef pthread_t ZixThread;
 typedef void*     ZixThreadResult;
@@ -118,7 +117,6 @@ zix_thread_join(ZixThread thread)
 
 /**
    @}
-   @}
 */
 
 #ifdef __cplusplus
diff --git a/include/zix/tree.h b/include/zix/tree.h
index eade134..f363ffc 100644
--- a/include/zix/tree.h
+++ b/include/zix/tree.h
@@ -1,4 +1,4 @@
-// Copyright 2011-2020 David Robillard <d@drobilla.net>
+// Copyright 2011-2022 David Robillard <d@drobilla.net>
 // SPDX-License-Identifier: ISC
 
 #ifndef ZIX_TREE_H
@@ -16,9 +16,8 @@ extern "C" {
 #endif
 
 /**
-   @addtogroup zix
-   @{
-   @name Tree
+   @defgroup zix_tree Tree
+   @ingroup zix
    @{
 */
 
@@ -118,7 +117,6 @@ zix_tree_iter_prev(ZixTreeIter* ZIX_NULLABLE i);
 
 /**
    @}
-   @}
 */
 
 #ifdef __cplusplus