continue documentation efforts

1 files changed, 200 insertions, 5 deletions

diff --git a/include/apos/bits.h b/include/apos/bits.h
index f99d5b4..69ab9b4 100644
--- a/include/apos/bits.h
+++ b/include/apos/bits.h
@@ -9,14 +9,92 @@
 #include <apos/types.h>
 #include <apos/builtin.h>
 
-#define is_set(x, y)     ((x) & (y))
-#define set_bit(x, y)    ((x) |= (y))
-#define clear_bit(x, y)  ((x) &= ~(y))
+/** @name Arithmetic integer bit manipulation. */
+/** @{ */
 
-#define is_nset(x, y)    (is_set((x), 1UL << (y)))
-#define set_nbit(x, y)   (set_bit((x), 1UL << (y)))
+/**
+ * Check if bits are set.
+ *
+ * @param x Value to check in.
+ * @param y Mask of bits to check.
+ * @return \c 0 if none of the bits aren't set, non-zero otherwise.
+ */
+#define is_set(x, y) ((x) & (y))
+
+/**
+ * Set bits.
+ *
+ * @param x Value to set in.
+ * @param y Mask of bits to set.
+ */
+#define set_bits(x, y) ((x) |= (y))
+
+/**
+ * Clear bits.
+ *
+ * @param x Value to clear in.
+ * @param y Mask of bits to clear.
+ */
+#define clear_bits(x, y) ((x) &= ~(y))
+
+/**
+ * Set bit.
+ * Wrapper around \ref set_bits() for when only one bit is changed,
+ * mostly just for readability purposes.
+ *
+ * @param x Value to set in.
+ * @param y Mask of bit to set.
+ */
+#define set_bit(x, y) set_bits(x, y)
+
+/** Clear bit.
+ * Wrapper around \ref clear_bits() for when only one bit is
+ * changed, mostly just for readability purposes.
+ *
+ * @param x Value to clear in.
+ * @param y Mask of bit to clear.
+ */
+#define clear_bit(x, y) clear_bits(x, y)
+
+/**
+ * Is nth bit set.
+ *
+ * @param x Value to check in.
+ * @param y Index of bit to check.
+ * @return \c 0 if bit is not set, non-zero otherwise.
+ */
+#define is_nset(x, y) (is_set((x), 1UL << (y)))
+
+/**
+ * Set nth bit.
+ *
+ * @param x Value to set in.
+ * @param y Index of bit to set.
+ */
+#define set_nbit(x, y) (set_bit((x), 1UL << (y)))
+
+/** Clear nth bit.
+ *
+ * @param x Value to clear in.
+ * @param y Index of bit to clear.
+ */
 #define clear_nbit(x, y) (clear_bit((x), 1UL << (y)))
 
+/** @} */
+
+/**
+ * @name Bitmap manipulation.
+ * A bitmap can be any number of bits in an array-like structure.
+ */
+/** @{ */
+
+/**
+ * Is nth bit set in bitmap.
+ *
+ * @param bmap Pointer to bitmap.
+ * @param n Index of bit to check.
+ * @return \c 0 if bit is not set, non-zero otherwise.
+ */
 static inline bool bitmap_is_set(void *bmap, size_t n)
 {
 	uint8_t *bitmap = bmap;
@@ -25,6 +103,12 @@ static inline bool bitmap_is_set(void *bmap, size_t n)
 	return is_nset(bitmap[i], r);
 }
 
+/**
+ * Set nth bit in bitmap.
+ *
+ * @param bmap Bitmap.
+ * @param n Index of bit to set.
+ */
 static inline void bitmap_set(void *bmap, size_t n)
 {
 	uint8_t *bitmap = bmap;
@@ -33,6 +117,12 @@ static inline void bitmap_set(void *bmap, size_t n)
 	set_nbit(bitmap[i], r);
 }
 
+/**
+ * Clear nth bit in bitmap.
+ *
+ * @param bmap Bitmap.
+ * @param n Index of bit to clear.
+ */
 static inline void bitmap_clear(void *bmap, size_t n)
 {
 	uint8_t *bitmap = bmap;
@@ -41,8 +131,30 @@ static inline void bitmap_clear(void *bmap, size_t n)
 	clear_nbit(bitmap[i], r);
 }
 
+/** @} */
+
+/**
+ * Swap byte order in \ref uint16_t.
+ *
+ * @param u \ref uint16_t to swap.
+ * @return \c u with its byte order swapper.
+ */
 uint16_t __bswap16(uint16_t u);
+
+/**
+ * Swap byte order in \ref uint32_t.
+ *
+ * @param u \ref uint32_t to swap.
+ * @return \c u with its byte order swapped.
+ */
 uint32_t __bswap32(uint32_t u);
+
+/**
+ * Swap byte order in \ref uint64_t.
+ *
+ * @param u \ref uint64_t to swap.
+ * @return \c u with its byte order swapped.
+ */
 uint64_t __bswap64(uint64_t u);
 
 #if __has_builtin(__builtin_bswap16)
@@ -58,22 +170,104 @@ uint64_t __bswap64(uint64_t u);
 #endif
 
 #if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+
+/**
+ * Convert big endian \ref uint16_t to cpu endianness.
+ *
+ * @param x \ref uint16_t to convert.
+ * @return \c x in cpu endianness.
+ */
 #define be16_to_cpu(x) __bswap16(x)
+
+/**
+ * Convert big endian \ref uint32_t to cpu endianness.
+ *
+ * @param x \ref uint32_t to convert.
+ * @return \c x in cpu endianness.
+ */
 #define be32_to_cpu(x) __bswap32(x)
+
+/**
+ * Convert big endian \ref uint64_t to cpu endianness.
+ *
+ * @param x \ref uint64_t to convert.
+ * @return \c x in cpu endianness.
+ */
 #define be64_to_cpu(x) __bswap64(x)
 
+/**
+ * Convert cpu endian \ref uint16_t to big endian.
+ *
+ * @param x \ref uint16_t to convert.
+ * @return \c x in big endian.
+ */
 #define cpu_to_be16(x) __bswap16(x)
+
+/**
+ * Convert cpu endian \ref uint32_t to big endian.
+ *
+ * @param x \ref uint32_t to convert.
+ * @return \c x in big endian.
+ */
 #define cpu_to_be32(x) __bswap32(x)
+
+/**
+ * Convert cpu endian to \ref uint64_t to big endian.
+ *
+ * @param x \ref uint64_t to convert.
+ * @return \c x in big endian.
+ */
 #define cpu_to_be64(x) __bswap64(x)
 
+/**
+ * Convert little endian \ref uint16_t to cpu endianness.
+ *
+ * @param x \ref uint16_t to convert.
+ * @return \c x in cpu endianness.
+ */
 #define le16_to_cpu(x) (x)
+
+/**
+ * Convert little endian \ref uint32_t to cpu endianness.
+ *
+ * @param x \ref uint32_t to convert.
+ * @return \c x in cpu endianness.
+ */
 #define le32_to_cpu(x) (x)
+
+/**
+ * Convert little endian \ref uint64_t to cpu endianness.
+ *
+ * @param x \ref uint64_t to convert.
+ * @return \c x in cpu endianness.
+ */
 #define le64_to_cpu(x) (x)
 
+/**
+ * Convert cpu endian \ref uint16_t to little endian.
+ *
+ * @param x \ref uint16_t to convert.
+ * @return \c x in little endian.
+ */
 #define cpu_to_le16(x) (x)
+
+/**
+ * Convert cpu endian \ref uint32_t to little endian.
+ *
+ * @param x \ref uint32_t to convert.
+ * @return \c x in little endian.
+ */
 #define cpu_to_le32(x) (x)
+
+/** Convert cpu endian \ref uint64_t to little endian.
+ *
+ * @param x \ref uint64_t to convert.
+ * @return \c x in little endian.
+ */
 #define cpu_to_le64(x) (x)
+
 #else
+
 #define be16_to_cpu(x) (x)
 #define be32_to_cpu(x) (x)
 #define be64_to_cpu(x) (x)
@@ -89,6 +283,7 @@ uint64_t __bswap64(uint64_t u);
 #define cpu_to_le16(x) __bswap16(x)
 #define cpu_to_le32(x) __bswap32(x)
 #define cpu_to_le64(x) __bswap64(x)
+
 #endif
 
 #endif /* APOS_BITS_H */