diff --git a/src/dbus.h b/src/dbus.h index 55594c1..a5af524 100644 --- a/src/dbus.h +++ b/src/dbus.h @@ -5,13 +5,14 @@ #include "notification.h" +/// The reasons according to the notification spec enum reason { - REASON_MIN = 1, - REASON_TIME = 1, - REASON_USER = 2, - REASON_SIG = 3, - REASON_UNDEF = 4, - REASON_MAX = 4, + REASON_MIN = 1, /**< Minimum value, useful for boundary checking */ + REASON_TIME = 1, /**< The notification timed out */ + REASON_USER = 2, /**< The user closed the notification */ + REASON_SIG = 3, /**< The daemon received a `NotificationClose` signal */ + REASON_UNDEF = 4, /**< Undefined reason not matching the previous ones */ + REASON_MAX = 4, /**< Maximum value, useful for boundary checking */ }; int initdbus(void); diff --git a/src/log.c b/src/log.c index ad777f6..3f41c0c 100644 --- a/src/log.c +++ b/src/log.c @@ -1,11 +1,16 @@ /* copyright 2012 - 2013 Sascha Kruse and contributors (see LICENSE for licensing information) */ +/** @file log.c + * @brief logging wrapper to use GLib's logging capabilities + */ + #include "log.h" #include static GLogLevelFlags log_level = G_LOG_LEVEL_WARNING; +/* see log.h */ static const char *log_level_to_string(GLogLevelFlags level) { switch (level) { @@ -19,6 +24,7 @@ static const char *log_level_to_string(GLogLevelFlags level) } } +/* see log.h */ void log_set_level_from_string(const char *level) { if (!level) @@ -51,10 +57,13 @@ void log_set_level(GLogLevelFlags level) log_level = level; } -/* +/** * Log handling function for GLib's logging wrapper * - * If the gpointer is valid, do not do anything + * @param log_domain Used only by GLib + * @param message_level Used only by GLib + * @param message Used only by GLib + * @param testing If not `NULL` (here: `true`), do nothing */ static void dunst_log_handler( const gchar *log_domain, @@ -81,12 +90,7 @@ static void dunst_log_handler( g_print("%s: %s\n", log_level_str, message); } -/* - * Initialise log handling. Can be called any time. - * - * If bool is %TRUE, it suppresses all logging output. - * Primarily used for testing - */ +/* see log.h */ void dunst_log_init(bool testing) { g_log_set_default_handler(dunst_log_handler, (void*)testing); diff --git a/src/log.h b/src/log.h index 3ca6e9d..9e58cca 100644 --- a/src/log.h +++ b/src/log.h @@ -16,9 +16,27 @@ #define DIE(...) do { LOG_C(__VA_ARGS__); exit(EXIT_FAILURE); } while (0) +/** + * @return the string representation of the given `level` + */ void log_set_level(GLogLevelFlags level); + +/** + * Set the current loglevel to `level` + * + * @param level The desired log level + * + * If `level` is `NULL`, nothing will be done. + * If `level` is an invalid value, nothing will be done. + */ void log_set_level_from_string(const char* level); +/** + * Initialise log handling. Can be called any time. + * + * @param testing If we're in testing mode and should + * suppress all output + */ void dunst_log_init(bool testing); #endif diff --git a/src/notification.h b/src/notification.h index 5b05e8a..11632a9 100644 --- a/src/notification.h +++ b/src/notification.h @@ -9,13 +9,14 @@ #define DUNST_NOTIF_MAX_CHARS 5000 +/// Representing the urgencies according to the notification spec enum urgency { - URG_NONE = -1, - URG_MIN = 0, - URG_LOW = 0, - URG_NORM = 1, - URG_CRIT = 2, - URG_MAX = 2, + URG_NONE = -1, /**< Urgency not set (invalid) */ + URG_MIN = 0, /**< Minimum value, useful for boundary checking */ + URG_LOW = 0, /**< Low urgency */ + URG_NORM = 1, /**< Normal urgency */ + URG_CRIT = 2, /**< Critical urgency */ + URG_MAX = 2, /**< Maximum value, useful for boundary checking */ }; typedef struct _raw_image { @@ -44,12 +45,12 @@ typedef struct _notification { char *category; enum urgency urgency; - char *icon; /* plain icon information (may be a path or just a name) */ - RawImage *raw_icon; /* passed icon data of notification, takes precedence over icon */ + char *icon; /**< plain icon information (may be a path or just a name) */ + RawImage *raw_icon; /**< passed icon data of notification, takes precedence over icon */ - gint64 start; /* begin of current display */ - gint64 timestamp; /* arrival time */ - gint64 timeout; /* time to display */ + gint64 start; /**< begin of current display */ + gint64 timestamp; /**< arrival time */ + gint64 timeout; /**< time to display */ Actions *actions; @@ -59,20 +60,20 @@ typedef struct _notification { char *colors[3]; /* Hints */ - bool transient; /* timeout albeit user is idle */ - int progress; /* percentage (-1: undefined) */ - int history_ignore; /* push to history or free directly */ + bool transient; /**< timeout albeit user is idle */ + int progress; /**< percentage (-1: undefined) */ + int history_ignore; /**< push to history or free directly */ /* internal */ - bool redisplayed; /* has been displayed before? */ - bool first_render; /* markup has been rendered before? */ - int dup_count; /* amount of duplicate notifications stacked onto this */ + bool redisplayed; /**< has been displayed before? */ + bool first_render; /**< markup has been rendered before? */ + int dup_count; /**< amount of duplicate notifications stacked onto this */ int displayed_height; /* derived fields */ - char *msg; /* formatted message */ - char *text_to_render; /* formatted message (with age and action indicators) */ - char *urls; /* urllist delimited by '\n' */ + char *msg; /**< formatted message */ + char *text_to_render; /**< formatted message (with age and action indicators) */ + char *urls; /**< urllist delimited by '\\n' */ } notification; notification *notification_create(void); diff --git a/src/queues.c b/src/queues.c index aec51bc..78f6c6a 100644 --- a/src/queues.c +++ b/src/queues.c @@ -1,5 +1,18 @@ /* copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing information) */ +/** + * @file queues.c + * @brief All important functions to handle the notification queues for + * history, entrance and currently displayed ones. + * + * Every method requires to have executed queues_init() at the start. + * + * A read only representation of the queue with the current notifications + * can get acquired by calling queues_get_displayed(). + * + * When ending the program or resetting the queues, tear down the stack with + * queues_teardown(). (And reinit with queues_init() if needed.) + */ #include "queues.h" #include @@ -12,9 +25,9 @@ #include "settings.h" /* notification lists */ -static GQueue *waiting = NULL; /* all new notifications get into here */ -static GQueue *displayed = NULL; /* currently displayed notifications */ -static GQueue *history = NULL; /* history of displayed notifications */ +static GQueue *waiting = NULL; /**< all new notifications get into here */ +static GQueue *displayed = NULL; /**< currently displayed notifications */ +static GQueue *history = NULL; /**< history of displayed notifications */ unsigned int displayed_limit = 0; int next_notification_id = 1; @@ -22,6 +35,7 @@ bool pause_displayed = false; static bool queues_stack_duplicate(notification *n); +/* see queues.h */ void queues_init(void) { history = g_queue_new(); @@ -29,29 +43,37 @@ void queues_init(void) waiting = g_queue_new(); } +/* see queues.h */ void queues_displayed_limit(unsigned int limit) { displayed_limit = limit; } -/* misc getter functions */ +/* see queues.h */ const GList *queues_get_displayed(void) { return g_queue_peek_head_link(displayed); } + +/* see queues.h */ unsigned int queues_length_waiting(void) { return waiting->length; } + +/* see queues.h */ unsigned int queues_length_displayed(void) { return displayed->length; } + +/* see queues.h */ unsigned int queues_length_history(void) { return history->length; } +/* see queues.h */ int queues_notification_insert(notification *n) { @@ -88,11 +110,11 @@ int queues_notification_insert(notification *n) return n->id; } -/* +/** * Replaces duplicate notification and stacks it * - * Returns %true, if notification got stacked - * Returns %false, if notification did not get stacked + * @return true, if notification got stacked + * @return false, if notification did not get stacked */ static bool queues_stack_duplicate(notification *n) { @@ -148,6 +170,7 @@ static bool queues_stack_duplicate(notification *n) return false; } +/* see queues.h */ bool queues_notification_replace_id(notification *new) { @@ -179,6 +202,7 @@ bool queues_notification_replace_id(notification *new) return false; } +/* see queues.h */ void queues_notification_close_id(int id, enum reason reason) { notification *target = NULL; @@ -212,12 +236,14 @@ void queues_notification_close_id(int id, enum reason reason) } } +/* see queues.h */ void queues_notification_close(notification *n, enum reason reason) { assert(n != NULL); queues_notification_close_id(n->id, reason); } +/* see queues.h */ void queues_history_pop(void) { if (g_queue_is_empty(history)) @@ -230,6 +256,7 @@ void queues_history_pop(void) g_queue_push_head(waiting, n); } +/* see queues.h */ void queues_history_push(notification *n) { if (!n->history_ignore) { @@ -244,6 +271,7 @@ void queues_history_push(notification *n) } } +/* see queues.h */ void queues_history_push_all(void) { while (displayed->length > 0) { @@ -255,6 +283,7 @@ void queues_history_push_all(void) } } +/* see queues.h */ void queues_check_timeouts(bool idle) { /* nothing to do */ @@ -290,6 +319,7 @@ void queues_check_timeouts(bool idle) } } +/* see queues.h */ void queues_update(void) { if (pause_displayed) { @@ -323,6 +353,7 @@ void queues_update(void) } } +/* see queues.h */ gint64 queues_get_next_datachange(gint64 time) { gint64 sleep = G_MAXINT64; @@ -354,27 +385,36 @@ gint64 queues_get_next_datachange(gint64 time) return sleep != G_MAXINT64 ? sleep : -1; } +/* see queues.h */ void queues_pause_on(void) { pause_displayed = true; } +/* see queues.h */ void queues_pause_off(void) { pause_displayed = false; } +/* see queues.h */ bool queues_pause_status(void) { return pause_displayed; } +/** + * Helper function for teardown_queues() to free a single notification + * + * @param data The notification to free + */ static void teardown_notification(gpointer data) { notification *n = data; notification_free(n); } +/* see queues.h */ void teardown_queues(void) { g_queue_free_full(history, teardown_notification); diff --git a/src/queues.h b/src/queues.h index 5636d0d..2fa9900 100644 --- a/src/queues.h +++ b/src/queues.h @@ -1,131 +1,183 @@ /* copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing information) */ +/** + * @file queues.c + */ + #ifndef DUNST_QUEUE_H #define DUNST_QUEUE_H #include "dbus.h" #include "notification.h" -/* - * Initialise neccessary queues +/** + * Initialise necessary queues + * + * @pre Do not call consecutively to avoid memory leaks + * or assure to have queues_teardown() executed before */ void queues_init(void); -/* +/** * Set maximum notification count to display * and store in displayed queue + * + * @param limit The maximum amount */ void queues_displayed_limit(unsigned int limit); -/* - * Return read only list of notifications +/** + * Receive the current list of displayed notifications + * + * @return read only list of notifications */ const GList *queues_get_displayed(void); -/* +/** * Returns the current amount of notifications, - * which are shown, waiting or already in history + * which are waiting to get displayed */ unsigned int queues_length_waiting(void); + +/** + * Returns the current amount of notifications, + * which are shown in the UI + */ unsigned int queues_length_displayed(void); + +/** + * Returns the current amount of notifications, + * which are already in history + */ unsigned int queues_length_history(void); -/* +/** * Insert a fully initialized notification into queues + * * Respects stack_duplicates, and notification replacement * - * If n->id != 0, n replaces notification with id n->id - * If n->id == 0, n gets a new id assigned + * @param n the notification to insert * - * Returns the assigned notification id - * If returned id == 0, the message was dismissed + * - If n->id != 0, n replaces notification n with id n->id + * - If n->id == 0, n gets a new id assigned + * + * @return `0`, the notification was dismissed and freed + * @return The new value of `n->id` */ int queues_notification_insert(notification *n); -/* +/** * Replace the notification which matches the id field of * the new notification. The given notification is inserted * right in the same position as the old notification. * - * Returns true, if a matching notification has been found - * and is replaced. Else false. + * @param new replacement for the old notification + * + * @return true, if a matching notification has been found and is replaced + * @return false, else */ bool queues_notification_replace_id(notification *new); -/* +/** * Close the notification that has n->id == id * - * Sends a signal and pushes it automatically to history. + * Sends a signal and pushes the selected notification automatically to history. * - * After closing, call wake_up to synchronize the queues with the UI - * (which closes the notification on screen) + * @param id The id of the notification to close + * @param reason The #reason to close + * + * @return the reason, why the notification got closed + * + * @post Call wake_up() to synchronize the queues with the UI + * (which closes the notification on screen) */ void queues_notification_close_id(int id, enum reason reason); -/* Close the given notification. SEE queues_notification_close_id. +/** + * Close the given notification. \see queues_notification_close_id(). * - * @n: (transfer full): The notification to close - * @reason: The reason to close + * @param n (transfer full) The notification to close + * @param reason The #reason to close * */ void queues_notification_close(notification *n, enum reason reason); -/* - * Pushed the latest notification of history to the displayed queue +/** + * Pushes the latest notification of history to the displayed queue * and removes it from history */ void queues_history_pop(void); -/* +/** * Push a single notification to history * The given notification has to be removed its queue * - * @n: (transfer full): The notification to push to history + * @param n (transfer full) The notification to push to history */ void queues_history_push(notification *n); -/* +/** * Push all waiting and displayed notifications to history */ void queues_history_push_all(void); -/* - * Check timeout of each notification and close it, if neccessary +/** + * Check timeout of each notification and close it, if necessary + * + * @param idle the program's idle status. Important to calculate the + * timeout for transient notifications */ void queues_check_timeouts(bool idle); -/* +/** * Move inserted notifications from waiting queue to displayed queue * and show them. In displayed queue, the amount of elements is limited - * to the amount set via queues_displayed_limit + * to the amount set via queues_displayed_limit() + * + * @post Call wake_up() to synchronize the queues with the UI + * (which closes old and shows new notifications on screen) */ void queues_update(void); -/* - * Return the distance to the next event in the queue, - * which forces an update visible to the user +/** + * Calculate the distance to the next event, when an element in the + * queues changes * - * This may be: + * @param time the current time * - * - notification hits timeout - * - notification's age second changes - * - notification's age threshold is hit + * @return the distance to the next event in the queue, which forces + * an update visible to the user. This may be: + * - notification hits timeout + * - notification's age second changes + * - notification's age threshold is hit */ gint64 queues_get_next_datachange(gint64 time); -/* +/** * Pause queue-management of dunst - * pause_on = paused (no notifications displayed) - * pause_off = running * - * Calling update_lists is neccessary + * @post Calling update_lists() is neccessary */ void queues_pause_on(void); + +/** + * Unpause (run) queue-management of dunst + * + * @post Calling update_lists() is neccessary + */ void queues_pause_off(void); + +/** + * Get the current status + * + * @return true if paused + * @return false if running + */ bool queues_pause_status(void); -/* - * Remove all notifications from all lists - * and free the notifications +/** + * Remove all notifications from all list and free the notifications + * + * @pre At least one time queues_init() called */ void teardown_queues(void);