Add docs

env_events.c

@@ -16,6 +16,10 @@
 #include "alertik.h"
 #include "notifiers.h"
 
+/*
+ * Environment events
+ */
+
 /* Regex params. */
 #define MAX_MATCHES 32
 
@@ -36,8 +40,8 @@ struct env_event env_events[MAX_ENV_EVENTS] = {0};
  * and slightly adapted: no error classification, because
  * I don't need to know, error is error.
  *
- * @param out Pointer to integer.
- * @param s String to be converted.
+ * @param out  Pointer to integer.
+ * @param s    String to be converted.
  *
  * @return Returns 0 if success and a negative number otherwise.
  */
@@ -62,7 +66,14 @@ static int str2int(int *out, const char *s)
 	return 0;
 }
 
-/**/
+/**
+ * @brief Retrieves the event string from the environment variables.
+ *
+ * @param ev_num Event number.
+ * @param str    String identifier.
+ *
+ * @return Returns the event string.
+ */
 static char *get_event_str(int ev_num, char *str)
 {
 	char *env;
@@ -73,7 +84,16 @@ static char *get_event_str(int ev_num, char *str)
 	return env;
 }
 
-/**/
+/**
+ * @brief Retrieves the index of the event from the environment variables.
+ *
+ * @param ev_num    Event number.
+ * @param str       String identifier.
+ * @param str_list  List of strings to match against.
+ * @param size      Size of the string list.
+ *
+ * @return Returns the index of the matching event.
+ */
 static int
 get_event_idx(int ev_num, char *str, const char *const *str_list, int size)
 {
@@ -85,7 +105,15 @@ get_event_idx(int ev_num, char *str, const char *const *str_list, int size)
 	panic("String parameter (%s) invalid for %s\n", env, str);
 }
 
-
+/**
+ * @brief Appends a character to the destination buffer if there is space.
+ *
+ * @param dst      Pointer to the destination buffer.
+ * @param dst_end  End of the destination buffer.
+ * @param c        Character to append.
+ *
+ * @return Returns 1 if the character was appended, 0 otherwise.
+ */
 static int append_dst(char **dst, const char *dst_end, char c) {
 	char *d = *dst;
 	if (d < dst_end) {
@@ -96,7 +124,19 @@ static int append_dst(char **dst, const char *dst_end, char c) {
 	return 0;
 }
 
-/**/
+/**
+ * @brief Handles match replacement in the event mask message.
+ *
+ * @param dst     Pointer to the destination buffer.
+ * @param dst_e   End of the destination buffer.
+ * @param c_msk   Pointer to the current position in the mask message.
+ * @param e_msk   End of the mask message.
+ * @param pmatch  Array of regex matches.
+ * @param env     Pointer to the environment event.
+ * @param log_ev  Pointer to the log event.
+ *
+ * @return Returns 1 if the replacement was handled, 0 otherwise.
+ */
 static int handle_match_replacement(
 	char       **dst,   char       *dst_e,
 	const char **c_msk, const char *e_msk,
@@ -140,7 +180,18 @@ static int handle_match_replacement(
 	return 1;
 }
 
-/**/
+/**
+ * @brief Creates a masked message based on the base mask string
+ * and the matches found.
+ *
+ * @param env       Pointer to the environment event.
+ * @param pmatch    Array of regex matches.
+ * @param log_ev    Pointer to the log event.
+ * @param buf       Buffer to store the masked message.
+ * @param buf_size  Size of the buffer.
+ *
+ * @return Returns the pointer to the end of the masked message.
+ */
 static char*
 create_masked_message(struct env_event *env, regmatch_t *pmatch,
 	struct log_event *log_ev, char *buf, size_t buf_size)
@@ -199,7 +250,14 @@ create_masked_message(struct env_event *env, regmatch_t *pmatch,
 	return dst;
 }
 
-/**/
+/**
+ * @brief Handles a log event with a regex match.
+ *
+ * @param ev      Pointer to the log event.
+ * @param idx_env Index of the environment event.
+ *
+ * @return Returns 1 if the event was handled, 0 otherwise.
+ */
 static int handle_regex(struct log_event *ev, int idx_env)
 {
 	char time_str[32]               = {0};
@@ -257,7 +315,14 @@ static int handle_regex(struct log_event *ev, int idx_env)
 	return 1;
 }
 
-/**/
+/**
+ * @brief Handles a log event with a substring match.
+ *
+ * @param ev       Pointer to the log event.
+ * @param idx_env  Index of the environment event.
+ *
+ * @return Returns 1 if the event was handled, 0 otherwise.
+ */
 static int handle_substr(struct log_event *ev, int idx_env)
 {
 	int notif_idx;

events.c

@@ -13,6 +13,10 @@
 #include "notifiers.h"
 #include "log.h"
 
+/*
+ * Static events
+ */
+
 /* Misc. */
 #define MAX_MATCHES 32
 static regmatch_t pmatch[MAX_MATCHES];
@@ -31,7 +35,14 @@ struct static_event static_events[NUM_EVENTS] = {
 	/* Add new handlers here. */
 };
 
-/**/
+/**
+ * @brief Retrieves the event string from the environment variables.
+ *
+ * @param ev_num Event number.
+ * @param str    String identifier.
+ *
+ * @return Returns the event string.
+ */
 static char *get_event_str(long ev_num, char *str)
 {
 	char *env;
@@ -42,7 +53,16 @@ static char *get_event_str(long ev_num, char *str)
 	return env;
 }
 
-/**/
+/**
+ * @brief Retrieves the index of the event from the environment variables.
+ *
+ * @param ev_num    Event number.
+ * @param str       String identifier.
+ * @param str_list  List of strings to match against.
+ * @param size      Size of the string list.
+ *
+ * @return Returns the index of the matching event.
+ */
 static int
 get_event_idx(long ev_num, char *str, const char *const *str_list, int size)
 {
@@ -173,6 +193,18 @@ int init_static_events(void)
 ///////////////////////////// FAILED LOGIN ATTEMPTS ///////////////////////////
 ///////////////////////////////////////////////////////////////////////////////
 
+/**
+ * @brief Parses the message pointed by @p msg and saves the
+ * read mac-address and interface in @p mac_addr and @wifi_iface.
+ *
+ * @param msg         Buffer to be read and parsed.
+ * @param wifi_iface  Output buffer that will contain the parsed
+ *                    device interface.
+ * @param mac_addr    Output buffer that will contain the parsed
+ *                    mac address.
+ *
+ * @return Returns 0 if success, -1 otherwise.
+ */
 static int
 parse_login_attempt_msg(const char *msg, char *wifi_iface, char *mac_addr)
 {
@@ -207,6 +239,14 @@ parse_login_attempt_msg(const char *msg, char *wifi_iface, char *mac_addr)
 	return (0);
 }
 
+/**
+ * @brief For a given log event @p ev and offset index @p idx_env,
+ * handle the event and send a notification message to the
+ * configured notifier.
+ *
+ * @param ev       Log event structure.
+ * @param idx_env  Event index.
+ */
 static void handle_wifi_login_attempts(struct log_event *ev, int idx_env)
 {
 	char time_str[32]   = {0};

log.c

@@ -16,6 +16,10 @@
 #include "events.h"
 #include "log.h"
 
+/*
+ * Alertik's log routines
+ */
+
 static pthread_mutex_t log_mutex = PTHREAD_MUTEX_INITIALIZER;
 static int curr_file;
 
@@ -49,7 +53,15 @@ out:
 	pthread_mutex_unlock(&log_mutex);
 }
 
-/**/
+/**
+ * @brief Format the current time passed as @p time
+ * into the buffer @p time_str.
+ *
+ * @param time     Time to be formated as string.
+ * @param time_str Output buffer.
+ *
+ * @return Returns the output buffer.
+ */
 char *get_formatted_time(time_t time, char *time_str)
 {
 	strftime(
@@ -61,7 +73,12 @@ char *get_formatted_time(time_t time, char *time_str)
 	return time_str;
 }
 
-/**/
+/**
+ * @brief Receives a formated string and outputs to stdout
+ * with the current timestamp.
+ *
+ * @param fmt String format.
+ */
 void log_msg(const char *fmt, ...)
 {
 	char time_str[32] = {0};
@@ -75,7 +92,12 @@ void log_msg(const char *fmt, ...)
 	close_log_file();
 }
 
-/**/
+/**
+ * @brief For a given log event @p ev, print the log event
+ * into the log file (wheter stdout or an actual file).
+ *
+ * @param ev Log event to be printed.
+ */
 void print_log_event(struct log_event *ev)
 {
 	char time_str[32] = {0};
@@ -85,7 +107,9 @@ void print_log_event(struct log_event *ev)
 	close_log_file();
 }
 
-/**/
+/**
+ * @brief Initializes the logging routines.
+ */
 void log_init(void) {
 	atexit(close_log_file);
 #ifndef USE_FILE_AS_LOG

notifiers.c

@@ -26,17 +26,29 @@ size_t libcurl_noop_cb(void *ptr, size_t size, size_t nmemb, void *data) {
 	return size * nmemb;
 }
 
-/**/
+/**
+ * @brief Just updates the time (Epoch) of the last sent
+ * notify.
+ */
 void update_notify_last_sent(void) {
 	time_last_sent_notify = time(NULL);
 }
 
-/**/
+/**
+ * @brief Checks if the current time is within or not
+ * the minimal threshold to send a nofication.
+ *
+ * @return Returns 1 if within the range (can send nofications),
+ * 0 otherwise.
+ */
 int is_within_notify_threshold(void) {
 	return (time(NULL) - time_last_sent_notify) > LAST_SENT_THRESHOLD_SECS;
 }
 
+////////////////////////////////////////////////////////////////////////////////
 //////////////////////////////// TELEGRAM //////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////////
+
 /* Telegram & request settings. */
 static char *telegram_bot_token;
 static char *telegram_chat_id;

syslog.c

@@ -32,7 +32,11 @@ static pthread_cond_t fifo_new_log_entry = PTHREAD_COND_INITIALIZER;
 static int syslog_push_msg_into_fifo(const char *, time_t);
 
 
-/* Create an UDP socket to read from. */
+/**
+ * @brief Create an UDP socket to read from.
+ *
+ * @return Returns the UDP socket fd if success.
+ */
 int syslog_create_udp_socket(void)
 {
 	struct sockaddr_in svaddr;
@@ -60,7 +64,14 @@ int syslog_create_udp_socket(void)
 	return fd;
 }
 
-/**/
+/**
+ * @brief Receives a new UDP message and then adds it
+ * to the message queue.
+ *
+ * @param fd UDP file descriptor to receive from.
+ *
+ * @return Returns 0 if success, -1 otherwise.
+ */
 int syslog_enqueue_new_upd_msg(int fd)
 {
 	struct sockaddr_storage cli = {0};
@@ -84,6 +95,16 @@ int syslog_enqueue_new_upd_msg(int fd)
 
 
 ///////////////////////////////// FIFO ////////////////////////////////////////
+/**
+ * @brief For a given message @p msg and a timestamp @p timestamp,
+ * adds both to the message queue and then wakes up the waiting
+ * thread.
+ *
+ * @param msg       Read message from UDP.
+ * @param timestamp Current timestamp.
+ *
+ * @return Returns 0 if success, -1 otherwise.
+ */
 static int syslog_push_msg_into_fifo(const char *msg, time_t timestamp)
 {
 	int next;
@@ -108,6 +129,14 @@ static int syslog_push_msg_into_fifo(const char *msg, time_t timestamp)
 	return 0;
 }
 
+/**
+ * @brief Pops a single message from the message queue (if any),
+ * and saves it into @p ev.
+ *
+ * @param ev Target buffer to the retrieved log event.
+ *
+ * @return Returns 0.
+ */
 int syslog_pop_msg_from_fifo(struct log_event *ev)
 {
 	int next;