* doxygen comments in database.[ch]

src/database.c

@@ -19,9 +19,9 @@
 #include "bitmap.h"
 
 struct _simdb_t {
-  int fd;
+  int fd;               /**< database file descriptor */
-  int flags;
+  int flags;            /**< database flags and capabilities, see SIMDB_FLAGS_* and SIMDB_CAP_* defines */
-  char path[PATH_MAX];
+  char path[PATH_MAX];  /**< path to database file */
 };
 
 #define DB_READ(db, buf, len, off) \

src/database.h

@@ -1,52 +1,71 @@
 #ifndef HAS_DATABASE_H
 #define HAS_DATABASE_H 1
 
-#define SIMDB_REC_LEN 48
+/**
-#define SIMDB_VERSION  2
+ * @file
+ * @brief Exportable simdb functions, defines & structs
+ */
 
-/* runtime flags */
+#define SIMDB_VERSION  2  /**< database format version */
-#define SIMDB_FLAG_WRITE    1 << (0 + 0)
+#define SIMDB_REC_LEN 48  /**< record length, in bytes */
 
-/* database capabilities */
+/**
-#define SIMDB_CAP_BITMAP    1 << (8 + 0)
+ * @defgroup SIMDBFlags Database runtime flags
-#define SIMDB_CAP_COLORS    1 << (8 + 1)
+ *  @{ */
-#define SIMDB_CAP_RATIO     1 << (8 + 2)
+#define SIMDB_FLAG_WRITE    1 << (0 + 0)  /**< database has write access */
-/* 3 used, 5 reserved */
+/** @} */
 
-#define SIMDB_SUCCESS          0
+/**
-/* database errors */
+ * @defgroup SIMDBCaps Database capabilities
-#define SIMDB_ERR_SYSTEM      -1 /* see errno for details */
+ * @{ */
-#define SIMDB_ERR_OOM         -2 /* can't allocate memory */
+#define SIMDB_CAP_BITMAP    1 << (8 + 0)  /**< database can compare images by luma bitmaps */
-#define SIMDB_ERR_CORRUPTDB   -3 /* empty or currupted database */
+#define SIMDB_CAP_COLORS    1 << (8 + 1)  /**< database can compare images by color levels */
-#define SIMDB_ERR_WRONGVERS   -4 /* database version mismatch */
+#define SIMDB_CAP_RATIO     1 << (8 + 2)  /**< database can compare images by ratio */
-#define SIMDB_ERR_NXRECORD    -5 /* no such record in database */
+/* 3 used, 5 reserved */
-#define SIMDB_ERR_READONLY    -6 /* database opened in read-only mode */
+/** @} */
 
-typedef struct _simdb_t simdb_t; /* opaque database type */
+/**
+ * @defgroup SIMDBErrors Database error codes
+ * @{ */
+#define SIMDB_SUCCESS          0 /**< success */
+#define SIMDB_ERR_SYSTEM      -1 /**< see errno for details */
+#define SIMDB_ERR_OOM         -2 /**< can't allocate memory */
+#define SIMDB_ERR_CORRUPTDB   -3 /**< empty or corrupted database */
+#define SIMDB_ERR_WRONGVERS   -4 /**< database version mismatch */
+#define SIMDB_ERR_NXRECORD    -5 /**< no such record in database */
+#define SIMDB_ERR_READONLY    -6 /**< database opened in read-only mode */
+/** @} */
+
+/** opaque database handler */
+typedef struct _simdb_t simdb_t;
 
-#define REC_OFF_RU  0 /* record is used */
+/**
-#define REC_OFF_CR  1 /* color level: red */
+ * @defgroup SIMDBRecOffsets Sample data parts offset in database record
-#define REC_OFF_CG  2 /* color level: green */
+ * @{ */
-#define REC_OFF_CB  3 /* color level: blue */
+#define REC_OFF_RU  0 /**< record is used */
-#define REC_OFF_IW  4 /* image width  */
+#define REC_OFF_CR  1 /**< color level: red */
-#define REC_OFF_IH  6 /* image height */
+#define REC_OFF_CG  2 /**< color level: green */
-#define REC_OFF_BM 16 /* image bitmap */
+#define REC_OFF_CB  3 /**< color level: blue */
+#define REC_OFF_IW  4 /**< image width  */
+#define REC_OFF_IH  6 /**< image height */
+#define REC_OFF_BM 16 /**< image bitmap */
+/** @} */
 
 /**
  * block of sequental records of database
  */
 typedef struct {
-  uint64_t start;
+  uint64_t start;      /**< first record number of block */
-  size_t records;
+  size_t records;      /**< records count */
-  unsigned char *data;
+  unsigned char *data; /**< raw records data */
 } simdb_block_t;
 
 /**
  * database record
  */
 typedef struct {
-  uint64_t num;
+  uint64_t num;                      /**< record number in database */
-  unsigned char data[SIMDB_REC_LEN];
+  unsigned char data[SIMDB_REC_LEN]; /**< record raw data */
 } simdb_rec_t;
 
 /**
@@ -68,15 +87,6 @@ typedef struct {
   float diff_bitmap;  /**< difference of bitmap */
 } simdb_match_t;
 
-/**
- * @returns 1 on success, 0 if record missing and <0 on error
- */
-int simdb_read_rec (simdb_t *db, simdb_rec_t *rec);
-int simdb_write_rec(simdb_t *db, simdb_rec_t *rec);
-
-int simdb_read_blk (simdb_t *db, simdb_block_t *blk);
-int simdb_write_blk(simdb_t *db, simdb_block_t *blk);
-
 /**
  * @brief Creates empty database at given path
  * @param path Path to database
@@ -104,12 +114,19 @@ void simdb_close(simdb_t *db);
 
 /**
  * @brief Get error desctiption by error code
- * @param error Error code, see SIMDB_ERR_* defines above
+ * @param code Error code, see SIMDB_ERR_* defines above
  */
 const char * simdb_error(int code);
 
 /**
- * @returns: >0 if found some matches, 0 if nothing found, <0 on error
+ * @brief Search compare given record in database to other images
+ * @param db Database handle
+ * @param sample Record sample
+ * @param search Search parameters
+ * @param matches Pointer to storage for found matches
+ * @retval >0 if found some matches
+ * @retval  0 if nothing found
+ * @retval <0 on error
  */
 int
 simdb_search(simdb_t         * const db,
@@ -118,7 +135,37 @@ simdb_search(simdb_t         * const db,
              simdb_match_t  ** matches);
 
 /**
- * @returns: number of records in database
+ * @brief Read single record from database
+ * @param db  Database handle
+ * @param rec Record struct
+ * @note @a num member of @a rec struct should be set
+ * @retval  1 on success
+ * @retval  0 if record exists but not used,
+ * @retval <0 on error (system error or record missing)
+ */
+int simdb_read_rec (simdb_t *db, simdb_rec_t *rec);
+/**
+ * @brief Write single record to database
+ * @param db  Database handle
+ * @param rec Record struct to write
+ * @note @a num member of @a rec struct should be set
+ * @retval  1 on success
+ * @retval <0 on error (system error or record missing)
+ */
+int simdb_write_rec(simdb_t *db, simdb_rec_t *rec);
+
+/**
+ * @brief Read continious records block from database
+ * @param db  Database handle
+ * @param blk Block struct
+ * @note @a start and @a records members of @a blk struct should be set
+ * @retval >=0 As number of records actually read
+ * @retval  <0 on error
+ */
+int simdb_read_blk (simdb_t *db, simdb_block_t *blk);
+
+/**
+ * @brief Get database capacity
  */
 uint64_t
 simdb_records_count(simdb_t * const db);
@@ -133,9 +180,11 @@ simdb_usage_map(simdb_t * const db,
 
 /**
  * @brief   Fills buffer 'map' according to records existense in given range
- * @param   offset  start of slice position
+ * @param   db      Database handler
- * @param   limit   slice size
+ * @param   map     Pointer for storing allocated usage map
- * @returns records processed (and also buffer size)
+ * @param   offset  Start of slice position
+ * @param   limit   Slice size
+ * @returns Records processed (and also buffer size)
 */
 uint16_t
 simdb_usage_slice(simdb_t  * const db,