From 6a182f6da1afda96de93467aa15827cefdad40af Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Sun, 23 Oct 2022 12:17:22 -0400
Subject: Add missing documentation

---
 include/zix/allocator.h      | 12 ++++++------
 include/zix/attributes.h     | 22 +++++++++++-----------
 include/zix/bump_allocator.h |  1 +
 include/zix/hash.h           |  6 +++---
 4 files changed, 21 insertions(+), 20 deletions(-)

(limited to 'include')

diff --git a/include/zix/allocator.h b/include/zix/allocator.h
index 26db6d3..34ee091 100644
--- a/include/zix/allocator.h
+++ b/include/zix/allocator.h
@@ -96,12 +96,12 @@ typedef void (*ZixAlignedFreeFunc)( //
 
 /// Definition of ZixAllocator
 struct ZixAllocatorImpl {
-  ZixMallocFunc ZIX_NONNULL       malloc;
-  ZixCallocFunc ZIX_NONNULL       calloc;
-  ZixReallocFunc ZIX_NONNULL      realloc;
-  ZixFreeFunc ZIX_NONNULL         free;
-  ZixAlignedAllocFunc ZIX_NONNULL aligned_alloc;
-  ZixAlignedFreeFunc ZIX_NONNULL  aligned_free;
+  ZixMallocFunc ZIX_NONNULL       malloc;        ///< Allocate
+  ZixCallocFunc ZIX_NONNULL       calloc;        ///< Allocate and zero
+  ZixReallocFunc ZIX_NONNULL      realloc;       ///< Reallocate
+  ZixFreeFunc ZIX_NONNULL         free;          ///< Free
+  ZixAlignedAllocFunc ZIX_NONNULL aligned_alloc; ///< Allocate aligned
+  ZixAlignedFreeFunc ZIX_NONNULL  aligned_free;  ///< Free aligned
 };
 
 /// Return the default allocator which simply uses the system allocator
diff --git a/include/zix/attributes.h b/include/zix/attributes.h
index ea18760..9a25f9c 100644
--- a/include/zix/attributes.h
+++ b/include/zix/attributes.h
@@ -15,8 +15,8 @@
 #  define ZIX_BEGIN_DECLS extern "C" {
 #  define ZIX_END_DECLS }
 #else
-#  define ZIX_BEGIN_DECLS
-#  define ZIX_END_DECLS
+#  define ZIX_BEGIN_DECLS ///< Begin public API definitions
+#  define ZIX_END_DECLS   ///< End public API definitions
 #endif
 
 // ZIX_API must be used to decorate things in the public API
@@ -32,15 +32,15 @@
 #  endif
 #endif
 
-// GCC pure/const/malloc attributes
+// GCC function attributes
 #ifdef __GNUC__
 #  define ZIX_PURE_FUNC __attribute__((pure))
 #  define ZIX_CONST_FUNC __attribute__((const))
 #  define ZIX_MALLOC_FUNC __attribute__((malloc))
 #else
-#  define ZIX_PURE_FUNC
-#  define ZIX_CONST_FUNC
-#  define ZIX_MALLOC_FUNC
+#  define ZIX_PURE_FUNC   ///< Only reads memory
+#  define ZIX_CONST_FUNC  ///< Only reads its parameters
+#  define ZIX_MALLOC_FUNC ///< Allocates memory
 #endif
 
 /// A pure function in the public API that only reads memory
@@ -62,7 +62,7 @@
 #ifdef __GNUC__
 #  define ZIX_LOG_FUNC(fmt, arg1) __attribute__((format(printf, fmt, arg1)))
 #else
-#  define ZIX_LOG_FUNC(fmt, arg1)
+#  define ZIX_LOG_FUNC(fmt, arg1) ///< A function with printf-like parameters
 #endif
 
 // Unused parameter macro to suppresses warnings and make it impossible to use
@@ -73,7 +73,7 @@
 #elif defined(_MSC_VER)
 #  define ZIX_UNUSED(name) __pragma(warning(suppress : 4100)) name
 #else
-#  define ZIX_UNUSED(name) name
+#  define ZIX_UNUSED(name) name ///< An unused parameter
 #endif
 
 // Clang nullability annotations
@@ -82,9 +82,9 @@
 #  define ZIX_NULLABLE _Nullable
 #  define ZIX_ALLOCATED _Null_unspecified
 #else
-#  define ZIX_NONNULL
-#  define ZIX_NULLABLE
-#  define ZIX_ALLOCATED
+#  define ZIX_NONNULL   ///< A non-null pointer
+#  define ZIX_NULLABLE  ///< A nullable pointer
+#  define ZIX_ALLOCATED ///< An allocated (possibly null) pointer
 #endif
 
 /**
diff --git a/include/zix/bump_allocator.h b/include/zix/bump_allocator.h
index 712ea46..bec45c8 100644
--- a/include/zix/bump_allocator.h
+++ b/include/zix/bump_allocator.h
@@ -45,6 +45,7 @@ typedef struct {
   size_t            capacity; ///< Size of buffer in bytes (the maximum top)
 } ZixBumpAllocator;
 
+/// Return a bump allocator that works within a provided buffer
 ZIX_API
 ZixBumpAllocator
 zix_bump_allocator(size_t capacity, void* ZIX_NONNULL buffer);
diff --git a/include/zix/hash.h b/include/zix/hash.h
index d362389..a5492a6 100644
--- a/include/zix/hash.h
+++ b/include/zix/hash.h
@@ -23,21 +23,21 @@ ZIX_BEGIN_DECLS
 #if defined(ZIX_HASH_KEY_TYPE)
 typedef ZIX_HASH_KEY_TYPE ZixHashKey;
 #else
-typedef void ZixHashKey;
+typedef void ZixHashKey;        ///< The type of a key within a record
 #endif
 
 // ZIX_HASH_RECORD_TYPE can be defined to make the API more type-safe
 #if defined(ZIX_HASH_RECORD_TYPE)
 typedef ZIX_HASH_RECORD_TYPE ZixHashRecord;
 #else
-typedef void ZixHashRecord;
+typedef void ZixHashRecord;     ///< The type of a hash table record
 #endif
 
 // ZIX_HASH_SEARCH_DATA_TYPE can be defined to make the API more type-safe
 #if defined(ZIX_HASH_SEARCH_DATA_TYPE)
 typedef ZIX_HASH_SEARCH_DATA_TYPE ZixHashSearchData;
 #else
-typedef void ZixHashSearchData;
+typedef void ZixHashSearchData; ///< User data for key comparison function
 #endif
 
 /**
-- 
cgit v1.2.1