From 0cf1db360b8f6d42024eacf6cfef1158665cdf0e Mon Sep 17 00:00:00 2001
From: Alex 'AdUser' Z <ad_user@runbox.com>
Date: Thu, 29 Dec 2016 13:45:40 +1000
Subject: [PATCH] * doxygen comments in bitmap.h

---
 src/bitmap.h | 41 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/src/bitmap.h b/src/bitmap.h
index 85c32b8..f8796de 100644
--- a/src/bitmap.h
+++ b/src/bitmap.h
@@ -1,26 +1,61 @@
 #ifndef HAS_BITMAP_H
 #define HAS_BITMAP_H 1
 
+/**
+ * @file
+ * @brief Functions for work with image bitmaps
+ */
+
+/** Bits per bitmap side (currently - 16) */
 #define BITMAP_SIDE 16
+/** Bitmap size in bytes (currently - 32) */
 #define BITMAP_SIZE (BITMAP_SIDE * (BITMAP_SIDE / 8))
+/** Total bits in bitmap (currently - 256) */
 #define BITMAP_BITS (BITMAP_SIZE * 8)
 
-#define CHAR_USED '@'
-#define CHAR_NONE '-'
+/** placeholders for various bit states */
+#define CHAR_USED '@' /**< bit is 1 */
+#define CHAR_NONE '-' /**< bit is 0 */
 
+/**
+ * @brief Compare two bitmaps
+ * @param a First bitmap to compare
+ * @param b Second bitmap to compare
+ * @returns Integer showing difference between bitmaps in bits (0-256)
+ */
 int
 bitmap_compare(const unsigned char *a,
                const unsigned char *b);
 
-int
+/**
+ * @brief Make difference map of to bitmaps
+ * @param diff Storage for difference map
+ * @param a    First bitmap to compare
+ * @param b    Second bitmap to compare
+ * @returns Size of generated map (now is @a BITMAP_SIZE)
+ */
+size_t
 bitmap_diffmap(unsigned char *diff,
                const unsigned char *a,
                const unsigned char *b);
 
+
+/**
+ * @brief Unpack BITmap to BYTEmap
+ * @param map Source bitmap
+ * @param buf Pointer to store generated bytemap
+ * @returns Size of generated bytemap (now is @a BITMAP_BITS)
+ */
 size_t
 bitmap_unpack(const unsigned char *map,
               unsigned char ** const buf);
 
+/**
+ * @brief Print bitmap to stdout as ascii-square
+ * @param map Source bitmap
+ * @note Heigth of "square" is equals to BITMAP_SIDE,
+ *   but width is BITMAP_SIDE x 2, for ease of reading
+ */
 void
 bitmap_print(const unsigned char *map);
 #endif