From 668ffa3febb116d20add6e9460fb1fb521a22e35 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Thu, 20 Oct 2022 21:03:17 -0400
Subject: Fix doc comments
---
include/zix/allocator.h | 8 +++-----
include/zix/attributes.h | 5 +++--
include/zix/bitset.h | 8 +++-----
include/zix/btree.h | 16 +++++++++++-----
include/zix/common.h | 29 +++++++++++++++--------------
include/zix/digest.h | 13 +++++++++----
include/zix/hash.h | 9 ++++-----
include/zix/ring.h | 8 ++++----
include/zix/sem.h | 6 ++----
include/zix/thread.h | 16 +++++++---------
include/zix/tree.h | 8 +++-----
11 files changed, 64 insertions(+), 62 deletions(-)
(limited to 'include')
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
--
cgit v1.2.1