* more doxygen comments

src/backend.h

@@ -10,6 +10,11 @@
 #include "config.h"
 #include "log.h"
 
+/**
+ * @file
+ * This header describes backend module definition and related routines
+ */
+
 /** backend module definition */
 typedef struct f2b_backend_t {
   void *h;   /**< dlopen handler */
@@ -42,7 +47,7 @@ typedef struct f2b_backend_t {
 /**
  * @brief Create module from config
  * @param config Pointer to section of config
- * @param init   Module init string
+ * @param id     Backend id
  * @returns Pointer to module metadata of NULL on error
  */
 f2b_backend_t * f2b_backend_create (f2b_config_section_t *config, const char *id);
@@ -53,14 +58,53 @@ f2b_backend_t * f2b_backend_create (f2b_config_section_t *config, const char *id
 void f2b_backend_destroy(f2b_backend_t *b);
 
 /* helpers */
+/**
+ * @brief Get last backend error
+ * @param b Pointer to backend struct
+ * @returns Pointer to string with description of last error
+ */
 const char *
      f2b_backend_error (f2b_backend_t *b);
+/**
+ * @brief Start given backend
+ * @param b Pointer to backend struct
+ * @returns true on success, false on error with setting last error
+ */
 bool f2b_backend_start (f2b_backend_t *b);
+/**
+ * @brief Stop given backend
+ * @param b Pointer to backend struct
+ * @returns true on success, false on error with setting last error
+ */
 bool f2b_backend_stop  (f2b_backend_t *b);
+/**
+ * @brief Perform maintenance of given backend
+ * @param b Pointer to backend struct
+ * @returns true on success, false on error with setting last error
+ */
 bool f2b_backend_ping  (f2b_backend_t *b);
 
+/**
+ * @brief Send command to ban given ip
+ * @param b  Pointer to backend struct
+ * @param ip IP address
+ * @returns true on success, false on error with setting last error
+ */
 bool f2b_backend_ban   (f2b_backend_t *b, const char *ip);
+/**
+ * @brief Check is given ip already banned by backend
+ * @param b  Pointer to backend struct
+ * @param ip IP address
+ * @returns true on success, false on error with setting last error
+ * @note Not all backends support this command
+ */
 bool f2b_backend_check (f2b_backend_t *b, const char *ip);
+/**
+ * @brief Send command to release given ip
+ * @param b  Pointer to backend struct
+ * @param ip IP address
+ * @returns true on success, false on error with setting last error
+ */
 bool f2b_backend_unban (f2b_backend_t *b, const char *ip);
 
 #endif /* F2B_BACKEND_H_ */

src/backends/backend.h

@@ -138,6 +138,7 @@ extern bool      ban(cfg_t *cfg, const char *ip);
  * @param cfg Module handler
  * @param ip IP address
  * @returns true on success, false on error with setting intenal error buffer
+ * @note If this action is meaningless for backend it should return true
  */
 extern bool    check(cfg_t *cfg, const char *ip);
 /**
@@ -145,6 +146,7 @@ extern bool    check(cfg_t *cfg, const char *ip);
  * @param cfg Module handler
  * @param ip IP address
  * @returns true on success, false on error with setting intenal error buffer
+ * @note If this action is meaningless for backend it should return true
  */
 extern bool    unban(cfg_t *cfg, const char *ip);
 /**

src/config.h

@@ -7,20 +7,36 @@
 #ifndef F2B_CONFIG_H_
 #define F2B_CONFIG_H_
 
-#define CONFIG_LINE_MAX 256
+/**
+ * @file
+ * This header describes f2b ini-style config structs and routines
+ */
 
+/**
+ * @def CONFIG_LINE_MAX
+ * Maximum length of config line
+ */
+#define CONFIG_LINE_MAX 256
+/**
+ * @def CONFIG_KEY_MAX
+ * Maximum length of parameter name
+ */
 #define CONFIG_KEY_MAX 32
+/**
+ * @def CONFIG_VAL_MAX
+ * Maximum length of parameter value
+ */
 #define CONFIG_VAL_MAX 192
 
 /** Section types in config */
 typedef enum f2b_section_type {
-  t_unknown = 0,
+  t_unknown = 0, /**< default value */
-  t_main,
+  t_main,        /**< [main] section */
-  t_defaults,
+  t_defaults,    /**< [defaults] section */
-  t_source,
+  t_source,      /**< [source:*] section */
-  t_filter,
+  t_filter,      /**< [filter:*] section */
-  t_backend,
+  t_backend,     /**< [backend:*] section */
-  t_jail,
+  t_jail,        /**< [jail:*] section */
 } f2b_section_type;
 
 /** Key-value line in config */

src/filter.h

@@ -10,6 +10,11 @@
 #include "config.h"
 #include "log.h"
 
+/**
+ * @file
+ * This header describes filter module definition and related routines
+ */
+
 /** filter module definition */
 typedef struct f2b_filter_t {
   void *h;   /**< dlopen handler */
@@ -36,12 +41,46 @@ typedef struct f2b_filter_t {
   void  (*destroy) (void *cfg);
 } f2b_filter_t;
 
+/**
+ * @brief Create module from config
+ * @param config Pointer to config section with module description
+ * @param id Filter id
+ * @returns Pointer to allocated module struct or NULL on error
+ */
 f2b_filter_t * f2b_filter_create  (f2b_config_section_t *config, const char *id);
+/**
+ * @brief Free module metadata
+ * @param f Pointer to module struct
+ */
+void f2b_filter_destroy (f2b_filter_t *f);
+
+/**
+ * @brief Get last filter error
+ * @param f Pointer to filter struct
+ * @returns Pointer to string with description of last error
+ */
 const char * f2b_filter_error (f2b_filter_t *f);
+/**
+ * @brief Append pattern to filter
+ * @param f Pointer to filter struct
+ * @param pattern Match pattern
+ * @returns true on success, false on error with setting last error
+ */
 bool f2b_filter_append(f2b_filter_t *f, const char *pattern);
-bool           f2b_filter_match   (f2b_filter_t *f, const char *line, char *buf, size_t buf_size);
+/**
-void           f2b_filter_destroy (f2b_filter_t *f);
+ * @brief Match a line against given filter
+ * @param f Pointer to filter struct
+ * @param line Line of data
+ * @param buf Match buffer
+ * @param bufsize Size of match buffer
+ * @returns false if no match and true otherwise with filling @a buf with matched token
+ */
+bool f2b_filter_match (f2b_filter_t *f, const char *line, char *buf, size_t bufsize);
 
+/* handlers for cmsg processing */
+/** handler of 'jail $JAIL filter reload' cmd */
 void f2b_filter_cmd_reload(char *buf, size_t bufsize, f2b_filter_t *f);
+/** handler of 'jail $JAIL filter stats' cmd */
 void f2b_filter_cmd_stats (char *buf, size_t bufsize, f2b_filter_t *f);
+
 #endif /* F2B_FILTER_H_ */

src/jail.h

@@ -14,6 +14,11 @@
 #include "filter.h"
 #include "backend.h"
 
+/**
+ * @file
+ * This header describes jail definition and related routines
+ */
+
 /** jail metadata struct */
 typedef struct f2b_jail_t {
   struct f2b_jail_t *next;   /**< pointer to next jail */
@@ -39,7 +44,10 @@ typedef struct f2b_jail_t {
   f2b_ipaddr_t  *ipaddrs; /**< list of known ip addresses */
 } f2b_jail_t;
 
-/** defined jails list */
+/**
+ * @var jails
+ * Global list of Defined jails
+ */
 extern f2b_jail_t *jails;
 
 /**
@@ -88,14 +96,14 @@ bool   f2b_jail_stop    (f2b_jail_t *jail);
  * @brief Get jail status
  * @param res Response buffer
  * @param ressize Size of buffer above
- * @param Jail pointer
+ * @param jail Jail pointer
  */
 void f2b_jail_cmd_status (char *res, size_t ressize, f2b_jail_t *jail);
 /**
  * @brief ipaddr manage routine in given jail
  * @param res Response buffer
  * @param ressize Size of buffer above
- * @param Jail pointer
+ * @param jail Jail pointer
  * @param op Operation for ipaddr >0 - ban, 0 - check, <0 - unban
  * @param ip Ip address
  */

src/log.h

@@ -7,15 +7,23 @@
 #ifndef F2B_LOG_H_
 #define F2B_LOG_H_
 
+/**
+ * @file
+ * This file contains logging routines
+ */
+
+/**
+ * @def LOGLINE_MAX
+ */
 #define LOGLINE_MAX 1024
 
 typedef enum {
-  log_debug = 0,
+  log_debug = 0, /**< diagnostic messages */
-  log_info  = 1,
+  log_info  = 1, /**< usefull, but not important messages */
-  log_note  = 2,
+  log_note  = 2, /**< ban/unban events */
-  log_warn  = 3,
+  log_warn  = 3, /**< something goes wrong */
-  log_error = 4,
+  log_error = 4, /**< error messages */
-  log_fatal = 5
+  log_fatal = 5  /**< critical error, program terminates */
 } log_msgtype_t;
 
 void f2b_log_msg(log_msgtype_t l, const char *fmt, ...)

src/source.h

@@ -10,6 +10,11 @@
 #include "config.h"
 #include "log.h"
 
+/**
+ * @file
+ * This header describes source module definition and related routines
+ */
+
 /** source module definition */
 typedef struct f2b_source_t {
   void *h;   /**< dlopen handler */
@@ -37,22 +42,44 @@ typedef struct f2b_source_t {
 
 /**
  * @brief Create module from config
- * @param config Pointer to section of config
+ * @param config Pointer to config section with module description
  * @param init   Module init string
  * @param errcb  Error callback
- * @returns Pointer to module metadata of NULL on error
+ * @returns Pointer to allocated module struct or NULL on error
  */
 f2b_source_t * f2b_source_create  (f2b_config_section_t *config, const char *init, void (*errcb)(const char *));
 /**
  * @brief Free module metadata
- * @param b Pointer to module struct
+ * @param s Pointer to module struct
  */
 void f2b_source_destroy (f2b_source_t *s);
 
-/* helpers */
+/**
+ * @brief Start given source
+ * @param s Pointer to source struct
+ * @returns true on success, false on error with setting last error
+ */
 bool f2b_source_start (f2b_source_t *s);
+/**
+ * @brief Get next line of data from given source
+ * @param s Pointer to source struct
+ * @param buf Buffer for data
+ * @param bufsize Size of buffer for data
+ * @param reset Reset source internals
+ * @returns false of no data available, true otherwise with setting @a buf
+ */
 bool f2b_source_next (f2b_source_t *s, char *buf, size_t bufsize, bool reset);
+/**
+ * @brief Stop given source
+ * @param s Pointer to source struct
+ * @returns true on success, false on error with setting last error
+ */
 bool f2b_source_stop (f2b_source_t *s);
+/**
+ * @brief Get last source error
+ * @param s Pointer to source struct
+ * @returns Pointer to string with description of last error
+ */
 const char * f2b_source_error (f2b_source_t *s);
 
 #endif /* F2B_SOURCE_H_ */