5 files changed, 64 insertions, 15 deletions
diff --git a/include/zix/allocator.h b/include/zix/allocator.h
index 97aa71c..5ab8bf8 100644
--- a/include/zix/allocator.h
+++ b/include/zix/allocator.h
@@ -87,7 +87,7 @@ typedef void* ZIX_ALLOCATED (*ZixAlignedAllocFunc)( //
 
    This works like the standard C free(), but must be used to free memory
    allocated with the aligned_alloc() method of the allocator.  This allows
-   portability to systems (like Windows) that can not use the same free function
+   portability to systems (like Windows) that can't use the same free function
    in these cases.
 */
 typedef void (*ZixAlignedFreeFunc)( //
diff --git a/include/zix/bitset.h b/include/zix/bitset.h
index 96816c8..491346d 100644
--- a/include/zix/bitset.h
+++ b/include/zix/bitset.h
@@ -17,10 +17,21 @@
    @{
 */
 
-/// A bitset (always referred to by pointer, actually an array)
+/**
+   A bitset element.
+
+   A bitset is an array that is always referred to by pointer.  This type is
+   the type of an element of that array (which stores some number of bits), so
+   a pointer to this type is a pointer to a bitset.
+*/
 typedef unsigned long ZixBitset;
 
-/// Tally of the number of bits in one ZixBitset element
+/**
+   Tally of the number of bits in one ZixBitset element.
+
+   Like #ZixBitset, this is the type of one element of a tally, which is a
+   parallel array to the bitset one, also always referred to by pointer.
+*/
 typedef uint8_t ZixBitsetTally;
 
 /// The number of bits per ZixBitset array element
@@ -31,33 +42,66 @@ typedef uint8_t ZixBitsetTally;
   (((n_bits) / ZIX_BITSET_BITS_PER_ELEM) + \
    (((n_bits) % ZIX_BITSET_BITS_PER_ELEM) ? 1 : 0))
 
-/// Clear a Bitset
+/**
+   Clear a bitset.
+
+   @param b The bitset to clear.
+   @param t The tally for `b` to update.
+   @param n_bits The number of bits in `b`.
+*/
 ZIX_API
 void
 zix_bitset_clear(ZixBitset* ZIX_NONNULL      b,
                  ZixBitsetTally* ZIX_NONNULL t,
                  size_t                      n_bits);
 
-/// Set bit `i` in `t` to 1
+/**
+   Set bit `i` in `b`.
+
+   @param b The bitset to set bit `i` in.
+   @param t The tally for `b` to update.
+   @param i The index of the bit to set.
+*/
 ZIX_API
 void
 zix_bitset_set(ZixBitset* ZIX_NONNULL      b,
                ZixBitsetTally* ZIX_NONNULL t,
                size_t                      i);
 
-/// Clear bit `i` in `t` (set to 0)
+/**
+   Clear bit `i` in `b`.
+
+   @param b The bitset to set bit `i` in.
+   @param t The tally for `b` to update.
+   @param i The index of the bit to set.
+*/
 ZIX_API
 void
 zix_bitset_reset(ZixBitset* ZIX_NONNULL      b,
                  ZixBitsetTally* ZIX_NONNULL t,
                  size_t                      i);
 
-/// Return the bit at index `i` in `b`
+/**
+   Return the bit at index `i` in `b`.
+
+   @param b The bitset to access.
+   @param i The index of the bit to return.
+   @return True if the bit is set (1), false otherwise (0).
+*/
 ZIX_PURE_API
 bool
 zix_bitset_get(const ZixBitset* ZIX_NONNULL b, size_t i);
 
-/// Return the number of set bits in `b` up to bit `i` (non-inclusive)
+/**
+   Return the number of set bits in `b` up to bit `i`.
+
+   The returned count is non-inclusive, that is, doesn't include bit `i`.
+
+   @param b The bitset to count.
+   @param t The tally for `b`.
+   @param i The end index to stop counting at.
+   @return The number of set bits in `b` from bit 0 to bit `i - 1`.
+*/
 ZIX_PURE_API
 size_t
 zix_bitset_count_up_to(const ZixBitset* ZIX_NONNULL      b,
@@ -65,8 +109,12 @@ zix_bitset_count_up_to(const ZixBitset* ZIX_NONNULL      b,
                        size_t                            i);
 
 /**
-   Return the number of set bits in `b` up to bit `i` (non-inclusive) if bit
-   `i` is set, or `(size_t)-1` otherwise.
+   Return the number of set bits in `b` up to bit `i` if it is set.
+
+   The returned count is non-inclusive, that is, doesn't include bit `i`.
+
+   @return The number of set bits in `b` from bit 0 to bit `i - 1` if bit `i`
+   is set, otherwise, `(size_t)-1`.
 */
 ZIX_PURE_API
 size_t
diff --git a/include/zix/bump_allocator.h b/include/zix/bump_allocator.h
index c054207..c69de92 100644
--- a/include/zix/bump_allocator.h
+++ b/include/zix/bump_allocator.h
@@ -37,7 +37,7 @@
      pointer, essentially serving as a cheap pop and pop-push, respectively.
 
    - Calling free() means that realloc() will fail and free() will do nothing
-     until the next allocation.  In other words, free() can not be used twice
+     until the next allocation.  In other words, free() can't be used twice
      in a row.
 
    - There is no relocation: realloc() always returns either the input pointer,
diff --git a/include/zix/ring.h b/include/zix/ring.h
index 04c3bda..181a7a3 100644
--- a/include/zix/ring.h
+++ b/include/zix/ring.h
@@ -34,8 +34,9 @@ typedef struct ZixRingImpl ZixRing;
 /**
    Create a new ring.
 
-   @param allocator Allocator for the ring.
-   @param size Size in bytes (note this may be rounded up).
+   @param allocator Allocator for the ring object and its array.
+
+   @param size Size of the ring in bytes (note this may be rounded up).
 
    At most `size` - 1 bytes may be stored in the ring at once.
 */
diff --git a/include/zix/sem.h b/include/zix/sem.h
index ea993fb..206e4e9 100644
--- a/include/zix/sem.h
+++ b/include/zix/sem.h
@@ -31,8 +31,8 @@ struct ZixSemImpl;
    A counting semaphore.
 
    This is an integer that is never negative, and has two main operations:
-   increment (post) and decrement (wait).  If a decrement can not be performed
-   (i.e. the value is 0) the caller will be blocked until another thread posts
+   increment (post) and decrement (wait).  If a decrement can't be performed
+   (because the value is 0) the caller will be blocked until another thread posts
    and the operation can succeed.
 
    Semaphores can be created with any starting value, but typically this will