* more doxygen comments

src/cmsg.h

@@ -1,18 +1,41 @@
 #ifndef F2B_CMSG_H_
 #define F2B_CMSG_H_
 
+/**
+ * @file
+ * This header contains definitions of control messages format and routines
+ */
+
+/**
+ * @def DATA_LEN_MAX
+ * Maximum length of data in packet
+ */
 #define DATA_LEN_MAX 1476 /* 1500 - (16 bytes of cmsg header + 8 bytes of udp) */
+/**
+ * @def DATA_ARGS_MAX
+ * Maximum count of data pieces in packet
+ */
 #define DATA_ARGS_MAX 6  /* number of args in data */
+/**
+ * @def F2B_PROTO_VER
+ * Protocol version of control message
+ */
 #define F2B_PROTO_VER 1
 
+/**
+ * @def CMSG_FLAG_NEED_REPLY
+ * Server should reply to this control message
+ */
 #define CMSG_FLAG_NEED_REPLY 0x01
+/**
+ * @def CMSG_FLAG_AUTH_PASS
+ * This control message contains password
+ */
 #define CMSG_FLAG_AUTH_PASS  0x02
 
 /**
- * @struct f2b_cmsg_t
+ * f2b control message
- * @brief f2b control message
+ * @note Use sendmsg/recvmsg and iovec structs to pack/unpack
- *
- * Use sendmsg/recvmsg and iovec structs to pack/unpack
  */
 typedef struct f2b_cmsg_t {
   char magic[3];   /**< magic string "F2B" */
@@ -29,7 +52,17 @@ typedef struct f2b_cmsg_t {
   /* end of data */
 } f2b_cmsg_t;
 
+/**
+ * @brief Convert every '\n' in data to '\0'
+ * @param msg Pointer to control message
+ */
 void f2b_cmsg_convert_args(f2b_cmsg_t *msg);
+/**
+ * @brief Fill @a argv array with pointers to found data pieces
+ * @param msg Pointer to control message
+ * @param argv Array of pointers
+ * @returns Number of found args
+ */
 int  f2b_cmsg_extract_args(const f2b_cmsg_t *msg, const char **argv);
 
 #endif /* F2B_CMSG_H_ */

src/csocket.c

@@ -108,14 +108,6 @@ f2b_csocket_rtimeout(int sock, float timeout) {
   f2b_log_msg(log_warn, "can't set recv timeout for csocket: %s", strerror(errno));
 }
 
-/**
- * @brief Recieve and unpack control message
- * @param csock Opened socket fd
- * @param cmsg  Control message pointer
- * @param addr  Pointer for sender address store
- * @param addrlen  Size of address storage
- * @return >0 on success, 0 on no avalilable messages, <0 on error
- */
 int
 f2b_csocket_recv(int csock, f2b_cmsg_t *cmsg, struct sockaddr_storage *addr, socklen_t *addrlen) {
   struct msghdr msg;
@@ -174,14 +166,6 @@ f2b_csocket_recv(int csock, f2b_cmsg_t *cmsg, struct sockaddr_storage *addr, soc
   return ret;
 }
 
-/**
- * @brief Pack and send control message
- * @param csock Opened socket fd
- * @param cmsg  Control message pointer
- * @param addr  Pointer for destination address store
- * @param addrlen  Size of address storage
- * @return >0 on success
- */
 int
 f2b_csocket_send(int csock, f2b_cmsg_t *cmsg, struct sockaddr_storage *addr, socklen_t *addrlen) {
   struct msghdr msg;
@@ -214,9 +198,6 @@ f2b_csocket_send(int csock, f2b_cmsg_t *cmsg, struct sockaddr_storage *addr, soc
   return ret;
 }
 
-/**
- * @return -1 on error, 0 on no messages, and > 0 on some messages processed
- */
 int
 f2b_csocket_poll(int csock, void (*cb)(const f2b_cmsg_t *cmsg, char *res, size_t ressize)) {
   char res[DATA_LEN_MAX + 1];

src/csocket.h

@@ -7,20 +7,73 @@
 #ifndef F2B_CSOCKET_H_
 #define F2B_CSOCKET_H_
 
+/**
+ * @file
+ * This file contains control socket manage routines
+ */
+
 #include <sys/socket.h>
 #include <arpa/inet.h>
 #include <sys/un.h>
 
+/**
+ * @brief Create UNIX socket with given path
+ * @param path Path to socket endpoint
+ * @returns Socket fd
+ */
 int  f2b_csocket_create (const char *path);
+/**
+ * @brief Close UNIX socket and unlink endpoint
+ * @param csock Socket fd
+ * @param path Path to socket endpoint
+ */
 void f2b_csocket_destroy(int csock, const char *path);
 
+/**
+ * @brief Connect to given socket
+ * @param spath path to control socket endpoint
+ * @param cpath Path to client socket's endpoint
+ * @returns Connected fd or -1 on error
+ */
 int  f2b_csocket_connect(const char *spath, const char *cpath);
-void f2b_csocket_disconnect(int sock, const char *cpath);
+/**
+ * @brief Close client connection and unlink client's endpoint
+ * @param csock Socket fd
+ * @param cpath Path to client socket's endpoint
+ */
+void f2b_csocket_disconnect(int csock, const char *cpath);
 
-void f2b_csocket_rtimeout(int sock, float timeout);
+/**
+ * @brief Set recieve rimeout on socket
+ * @param csock Socket fd
+ * @param timeout Timeout in seconds
+ */
+void f2b_csocket_rtimeout(int csock, float timeout);
 
+/**
+ * @brief Poll control socket for new messages
+ * @param csock Control socket fd
+ * @param cb Callback for handling message
+ * @returns -1 on error, 0 on no messages, and > 0 on some messages processed
+ */
 int f2b_csocket_poll(int csock, void (*cb)(const f2b_cmsg_t *cmsg, char *res, size_t ressize));
-int f2b_csocket_send(int csock, f2b_cmsg_t *cmsg, struct sockaddr_storage *addr, socklen_t *socklen);
+/**
-int f2b_csocket_recv(int csock, f2b_cmsg_t *cmsg, struct sockaddr_storage *addr, socklen_t *socklen);
+ * @brief Pack and send control message
+ * @param csock Opened socket fd
+ * @param cmsg  Control message pointer
+ * @param addr  Pointer for destination address store
+ * @param addrlen  Size of address storage
+ * @returns >0 on success
+ */
+int f2b_csocket_send(int csock, f2b_cmsg_t *cmsg, struct sockaddr_storage *addr, socklen_t *addrlen);
+/**
+ * @brief Recieve and unpack control message
+ * @param csock Opened socket fd
+ * @param cmsg  Control message pointer
+ * @param addr  Pointer for sender address store
+ * @param addrlen  Size of address storage
+ * @returns >0 on success, 0 on no avalilable messages, <0 on error
+ */
+int f2b_csocket_recv(int csock, f2b_cmsg_t *cmsg, struct sockaddr_storage *addr, socklen_t *addrlen);
 
 #endif /* F2B_CSOCKET_H_ */

src/ipaddr.h

@@ -11,6 +11,11 @@
 #include <netinet/in.h>
 #include <arpa/inet.h>
 
+/**
+ * @file
+ * This file contains definition of ipaddr struct and related routines
+ */
+
 #include "matches.h"
 
 /**
@@ -19,10 +24,7 @@
  */
 #define IPADDR_MAX 48 /* 8 x "ffff" + 7 x "::" + '\0' */
 
-/**
+/** Describes ip-address and it's metadata */
- * @struct f2b_ipaddr_t
- * Describes ip-address and it's metadata
- */
 typedef struct f2b_ipaddr_t {
   struct f2b_ipaddr_t *next; /**< pointer to next addr */
   int type;                  /**< address type, AF_INET/AF_INET6 */
@@ -60,9 +62,33 @@ void f2b_ipaddr_destroy(f2b_ipaddr_t *ipaddr);
  */
 void f2b_ipaddr_status (f2b_ipaddr_t *ipaddr, char *res, size_t ressize);
 
+/**
+ * @brief Append address to list
+ * @param list Pointer to ipaddr list (can be NULL)
+ * @param ipaddr Pointer to ipaddr struct for adding to list
+ * @returns Pointer to new address list
+ */
 f2b_ipaddr_t * f2b_addrlist_append(f2b_ipaddr_t *list, f2b_ipaddr_t *ipaddr);
+/**
+ * @brief Search for given ipaddr in list
+ * @param list Pointer to ipaddr list (can be NULL)
+ * @param addr IP address for search
+ * @returns Pointer to found struct or NULL if not found
+ */
 f2b_ipaddr_t * f2b_addrlist_lookup(f2b_ipaddr_t *list, const char *addr);
+/**
+ * @brief Remove given address from list
+ * @param list Pointer to ipaddr list (can be NULL)
+ * @param addr IP address for remove
+ * @returns Pointer to new address list or NULL if new list is empty
+ */
 f2b_ipaddr_t * f2b_addrlist_remove(f2b_ipaddr_t *list, const char *addr);
+/**
+ * @brief Free all addresses in list
+ * @param list Pointer to ipaddr list (can be NULL)
+ * @returns NULL
+ * @note Return value not void to match other functions
+ */
 f2b_ipaddr_t * f2b_addrlist_destroy(f2b_ipaddr_t *list);
 
 #endif /* F2B_IPADDR_H_ */

src/log.h

@@ -14,9 +14,11 @@
 
 /**
  * @def LOGLINE_MAX
+ * Maximum length of log message
  */
 #define LOGLINE_MAX 1024
 
+/** levels of log messages */
 typedef enum {
   log_debug = 0, /**< diagnostic messages */
   log_info  = 1, /**< usefull, but not important messages */
@@ -26,12 +28,31 @@ typedef enum {
   log_fatal = 5  /**< critical error, program terminates */
 } log_msgtype_t;
 
+/**
+ * @brief Write message to log
+ * @param l Level of message
+ * @param fmt Message format string
+ */
 void f2b_log_msg(log_msgtype_t l, const char *fmt, ...)
   __attribute__ ((format (printf, 2, 3)));
+/**
+ * @brief Logging wrapper for use in source module
+ * @param errstr Error string
+ */
 void f2b_log_error_cb(const char *errstr);
+/**
+ * @brief Limit logging messages by importance
+ * @param level Min level of messages for logging
+ */
 void f2b_log_set_level(const char *level);
+/**
+ * @brief Use logging to file
+ * @param path Path for logfile
+ */
 void f2b_log_to_file  (const char *path);
+/** @brief Use logging to stderr */
 void f2b_log_to_stderr();
+/** @brief Use logging to syslog */
 void f2b_log_to_syslog();
 
 #endif /* F2B_LOG_H_ */

src/matches.h

@@ -7,6 +7,11 @@
 #ifndef F2B_MATCHES_H_
 #define F2B_MATCHES_H_
 
+/**
+ * @file
+ * This file contains definition of ipaddr matches struct and related routines
+ */
+
 /** matches container */
 typedef struct {
   size_t hits;   /**< how many times this ip matched by filter */