Add initial doxygen documentation

src/dbus.h

@@ -5,13 +5,14 @@
 
 #include "notification.h"
 
+/// The reasons according to the notification spec
 enum reason {
-        REASON_MIN = 1,
+        REASON_MIN = 1,   /**< Minimum value, useful for boundary checking */
-        REASON_TIME = 1,
+        REASON_TIME = 1,  /**< The notification timed out */
-        REASON_USER = 2,
+        REASON_USER = 2,  /**< The user closed the notification */
-        REASON_SIG = 3,
+        REASON_SIG = 3,   /**< The daemon received a `NotificationClose` signal */
-        REASON_UNDEF = 4,
+        REASON_UNDEF = 4, /**< Undefined reason not matching the previous ones */
-        REASON_MAX = 4,
+        REASON_MAX = 4,   /**< Maximum value, useful for boundary checking */
 };
 
 int initdbus(void);

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 <glib.h>
 
 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);
 }
 
-/*
+/* see log.h */
- * Initialise log handling. Can be called any time.
- *
- * If bool is %TRUE, it suppresses all logging output.
- * Primarily used for testing
- */
 void dunst_log_init(bool testing)
 {
         g_log_set_default_handler(dunst_log_handler, (void*)testing);

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

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_NONE = -1, /**< Urgency not set (invalid) */
-        URG_MIN = 0,
+        URG_MIN = 0,   /**< Minimum value, useful for boundary checking */
-        URG_LOW = 0,
+        URG_LOW = 0,   /**< Low urgency */
-        URG_NORM = 1,
+        URG_NORM = 1,  /**< Normal urgency */
-        URG_CRIT = 2,
+        URG_CRIT = 2,  /**< Critical urgency */
-        URG_MAX = 2,
+        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) */
+        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 */
+        RawImage *raw_icon;  /**< passed icon data of notification, takes precedence over icon */
 
-        gint64 start;      /* begin of current display */
+        gint64 start;      /**< begin of current display */
-        gint64 timestamp;  /* arrival time */
+        gint64 timestamp;  /**< arrival time */
-        gint64 timeout;    /* time to display */
+        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 */
+        bool transient;     /**< timeout albeit user is idle */
-        int progress;       /* percentage (-1: undefined) */
+        int progress;       /**< percentage (-1: undefined) */
-        int history_ignore; /* push to history or free directly */
+        int history_ignore; /**< push to history or free directly */
 
         /* internal */
-        bool redisplayed;       /* has been displayed before? */
+        bool redisplayed;       /**< has been displayed before? */
-        bool first_render;      /* markup has been rendered before? */
+        bool first_render;      /**< markup has been rendered before? */
-        int dup_count;          /* amount of duplicate notifications stacked onto this */
+        int dup_count;          /**< amount of duplicate notifications stacked onto this */
         int displayed_height;
 
         /* derived fields */
-        char *msg;            /* formatted message */
+        char *msg;            /**< formatted message */
-        char *text_to_render; /* formatted message (with age and action indicators) */
+        char *text_to_render; /**< formatted message (with age and action indicators) */
-        char *urls;           /* urllist delimited by '\n' */
+        char *urls;           /**< urllist delimited by '\\n' */
 } notification;
 
 notification *notification_create(void);

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 <assert.h>
@@ -12,9 +25,9 @@
 #include "settings.h"
 
 /* notification lists */
-static GQueue *waiting   = NULL; /* all new notifications get into here */
+static GQueue *waiting   = NULL; /**< all new notifications get into here */
-static GQueue *displayed = NULL; /* currently displayed notifications */
+static GQueue *displayed = NULL; /**< currently displayed notifications */
-static GQueue *history   = NULL; /* history of 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
+ * @return true, if notification got stacked
- * Returns %false, if notification did not get 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);

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
+ * @param n the notification to insert
- * If n->id == 0, n gets a new id assigned
  *
- * Returns the assigned notification id
+ * - If n->id != 0, n replaces notification n with id n->id
- * If returned id == 0, the message was dismissed
+ * - 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
+ * @param new replacement for the old notification
- * and is replaced. Else false.
+ *
+ * @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
+ * @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
+ * @param n (transfer full) The notification to close
- * @reason: The reason 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,
+ * Calculate the distance to the next event, when an element in the
- * which forces an update visible to the user
+ * queues changes
  *
- * This may be:
+ * @param time the current time
  *
+ * @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
+ * Remove all notifications from all list and free the notifications
- * and free the notifications
+ *
+ * @pre At least one time queues_init() called
  */
 void teardown_queues(void);