Merge pull request #491 from bebehei/docs

Parsable markup documentation with doxygen

.gitignore

@@ -7,3 +7,4 @@ org.knopwob.dunst.service
 dunst.systemd.service
 dunstify
 test/test
+docs/internal/html

.travis.yml

@@ -1,6 +1,8 @@
 addons:
   apt:
     packages:
+      - doxygen
+      - graphviz
       - libdbus-1-dev
       - libx11-dev
       - libxrandr-dev
@@ -19,7 +21,7 @@ language: c
 before_install:
   - pip install --user cpp-coveralls
 script:
-  - CFLAGS="-fprofile-arcs -ftest-coverage -Werror" make all dunstify test-valgrind
+  - CFLAGS="-fprofile-arcs -ftest-coverage -Werror" make all dunstify test-valgrind doc-doxygen
   - coveralls
 compiler:
   - gcc

HACKING.md

@@ -1,5 +1,19 @@
 # Important notes on the code
 
+**You can generate an internal overview with doxygen. For this, use `make doc-doxygen` and you'll find an internal overview of all functions and symbols in `docs/internal/html`.**
+
+# Comments
+
+- Comment system is held similar to JavaDoc
+    - Use `@param` to describe all input parameters
+    - Documentation comments should start with a double star (`/**`)
+    - Append `()` to function names and prepend variables with `#` to properly reference them in the docs
+- Add comments to all functions and methods
+- Markdown inside the comments is allowed and also desired
+- Add the comments to the prototype. Doxygen will merge the protoype and implementation documentation anyways.
+  Except for **static** methods, add the documentation header to the implementation and *not to the prototype*.
+- Member documentation should happen with `/**<` and should span to the right side of the member
+
 ## Log messages
 
 ### Messages

Makefile

@@ -86,10 +86,12 @@ test-valgrind: test/test
 test/test: ${OBJ} ${TEST_OBJ}
 	${CC} ${CFLAGS} -o $@ ${TEST_OBJ} ${OBJ} ${LDFLAGS}
 
-.PHONY: doc
+.PHONY: doc doc-doxygen
 doc: docs/dunst.1
 docs/dunst.1: docs/dunst.pod
 	pod2man --name=dunst -c "Dunst Reference" --section=1 --release=${VERSION} $< > $@
+doc-doxygen:
+	doxygen docs/internal/Doxyfile
 
 .PHONY: service service-dbus service-systemd
 service: service-dbus
@@ -115,6 +117,7 @@ clean-dunstify:
 
 clean-doc:
 	rm -f docs/dunst.1
+	rm -fr docs/internal/html
 
 clean-tests:
 	rm -f test/test test/*.o

docs/internal/Doxyfile

@@ -0,0 +1,245 @@
+# Doxyfile 1.8.14
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = Dunst
+PROJECT_NUMBER         =
+PROJECT_BRIEF          = "Lightweight notification daemon"
+PROJECT_LOGO           =
+OUTPUT_DIRECTORY       = docs/internal
+CREATE_SUBDIRS         = NO
+ALLOW_UNICODE_NAMES    = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        =
+STRIP_FROM_INC_PATH    =
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                =
+TCL_SUBST              =
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+EXTENSION_MAPPING      =
+MARKDOWN_SUPPORT       = YES
+TOC_INCLUDE_HEADINGS   = 0
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = YES
+LOOKUP_CACHE_SIZE      = 0
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_PACKAGE        = YES
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = YES
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       =
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    =
+LAYOUT_FILE            =
+CITE_BIB_FILES         =
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = YES
+WARN_AS_ERROR          = YES
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           =
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = . \
+                         HACKING.md
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c \
+                         *.h
+RECURSIVE              = YES
+EXCLUDE                =
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = */test/greatest.h
+EXCLUDE_SYMBOLS        =
+EXAMPLE_PATH           =
+EXAMPLE_PATTERNS       = *
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             =
+INPUT_FILTER           =
+FILTER_PATTERNS        =
+FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE = HACKING.md
+#---------------------------------------------------------------------------
+# Configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = YES
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          =
+#---------------------------------------------------------------------------
+# Configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            =
+HTML_FOOTER            =
+HTML_STYLESHEET        =
+HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_FILES       =
+HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_GAMMA  = 80
+HTML_TIMESTAMP         = YES
+HTML_DYNAMIC_MENUS     = YES
+HTML_DYNAMIC_SECTIONS  = YES
+HTML_INDEX_NUM_ENTRIES = 0
+GENERATE_DOCSET        = NO
+GENERATE_HTMLHELP      = NO
+GENERATE_CHI           = NO
+GENERATE_QHP           = NO
+GENERATE_ECLIPSEHELP   = NO
+ECLIPSE_DOC_ID         = org.dunst-project.dunst
+DISABLE_INDEX          = NO
+GENERATE_TREEVIEW      = YES
+ENUM_VALUES_PER_LINE   = 4
+TREEVIEW_WIDTH         = 250
+EXT_LINKS_IN_WINDOW    = NO
+FORMULA_FONTSIZE       = 10
+FORMULA_TRANSPARENT    = YES
+USE_MATHJAX            = NO
+SEARCHENGINE           = YES
+SERVER_BASED_SEARCH    = NO
+EXTERNAL_SEARCH        = NO
+SEARCHENGINE_URL       =
+SEARCHDATA_FILE        = searchdata.xml
+EXTERNAL_SEARCH_ID     =
+EXTRA_SEARCH_MAPPINGS  =
+#---------------------------------------------------------------------------
+# Multiple disabled output formats
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+GENERATE_RTF           = NO
+GENERATE_MAN           = NO
+GENERATE_XML           = NO
+GENERATE_DOCBOOK       = NO
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           =
+INCLUDE_FILE_PATTERNS  =
+PREDEFINED             =
+EXPAND_AS_DEFINED      =
+SKIP_FUNCTION_MACROS   = YES
+#---------------------------------------------------------------------------
+# Configuration options related to external references
+#---------------------------------------------------------------------------
+TAGFILES               =
+GENERATE_TAGFILE       =
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+EXTERNAL_PAGES         = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = YES
+MSCGEN_PATH            =
+DIA_PATH               =
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = YES
+DOT_NUM_THREADS        = 0
+DOT_FONTNAME           = Helvetica
+DOT_FONTSIZE           = 10
+DOT_FONTPATH           =
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+UML_LIMIT_NUM_FIELDS   = 10
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = svg
+INTERACTIVE_SVG        = YES
+DOT_PATH               =
+DOTFILE_DIRS           =
+MSCFILE_DIRS           =
+DIAFILE_DIRS           =
+PLANTUML_JAR_PATH      =
+PLANTUML_CFG_FILE      =
+PLANTUML_INCLUDE_PATH  =
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES

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()
+const GList *queues_get_displayed(void)
 {
         return g_queue_peek_head_link(displayed);
 }
-unsigned int queues_length_waiting()
+
+/* see queues.h */
+unsigned int queues_length_waiting(void)
 {
         return waiting->length;
 }
-unsigned int queues_length_displayed()
+
+/* see queues.h */
+unsigned int queues_length_displayed(void)
 {
         return displayed->length;
 }
-unsigned int queues_length_history()
+
+/* 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,7 +202,8 @@ bool queues_notification_replace_id(notification *new)
         return false;
 }
 
-int queues_notification_close_id(int id, enum reason reason)
+/* see queues.h */
+void queues_notification_close_id(int id, enum reason reason)
 {
         notification *target = NULL;
 
@@ -210,16 +234,16 @@ int queues_notification_close_id(int id, enum reason reason)
                         signal_notification_closed(target, reason);
                 queues_history_push(target);
         }
-
-        return reason;
 }
 
-int queues_notification_close(notification *n, enum reason reason)
+/* see queues.h */
+void queues_notification_close(notification *n, enum reason reason)
 {
         assert(n != NULL);
-        return queues_notification_close_id(n->id, reason);
+        queues_notification_close_id(n->id, reason);
 }
 
+/* see queues.h */
 void queues_history_pop(void)
 {
         if (g_queue_is_empty(history))
@@ -232,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) {
@@ -246,6 +271,7 @@ void queues_history_push(notification *n)
         }
 }
 
+/* see queues.h */
 void queues_history_push_all(void)
 {
         while (displayed->length > 0) {
@@ -257,6 +283,7 @@ void queues_history_push_all(void)
         }
 }
 
+/* see queues.h */
 void queues_check_timeouts(bool idle)
 {
         /* nothing to do */
@@ -292,7 +319,8 @@ void queues_check_timeouts(bool idle)
         }
 }
 
-void queues_update()
+/* see queues.h */
+void queues_update(void)
 {
         if (pause_displayed) {
                 while (displayed->length > 0) {
@@ -325,6 +353,7 @@ void queues_update()
         }
 }
 
+/* see queues.h */
 gint64 queues_get_next_datachange(gint64 time)
 {
         gint64 sleep = G_MAXINT64;
@@ -356,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();
+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();
+unsigned int queues_length_waiting(void);
-unsigned int queues_length_displayed();
-unsigned int queues_length_history();
 
-/*
+/**
+ * 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
- * (which closes the notification on screen)
+ * @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)
  */
-int queues_notification_close_id(int id, enum reason reason);
+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
  * */
-int queues_notification_close(notification *n, enum reason reason);
+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 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
  *
- * - notification hits timeout
+ * @return the distance to the next event in the queue, which forces
- * - notification's age second changes
+ *         an update visible to the user. This may be:
- * - notification's age threshold is hit
+ *             - 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);
 

src/x11/screen.c

@@ -29,16 +29,16 @@ int randr_event_base = 0;
 static int randr_major_version = 0;
 static int randr_minor_version = 0;
 
-void randr_init();
+void randr_init(void);
-void randr_update();
+void randr_update(void);
-void xinerama_update();
+void xinerama_update(void);
-void screen_update_fallback();
+void screen_update_fallback(void);
 static void x_follow_setup_error_handler(void);
 static int x_follow_tear_down_error_handler(void);
 static int FollowXErrorHandler(Display *display, XErrorEvent *e);
 static Window get_focused_window(void);
 
-static double get_xft_dpi_value()
+static double get_xft_dpi_value(void)
 {
         static double dpi = -1;
         //Only run this once, we don't expect dpi changes during runtime
@@ -65,7 +65,7 @@ static double get_xft_dpi_value()
         return dpi;
 }
 
-void init_screens()
+void init_screens(void)
 {
         if (!settings.force_xinerama) {
                 randr_init();
@@ -87,7 +87,7 @@ void alloc_screen_ar(int n)
         screens_len = n;
 }
 
-void randr_init()
+void randr_init(void)
 {
         int randr_error_base = 0;
         if (!XRRQueryExtension(xctx.dpy, &randr_event_base, &randr_error_base)) {
@@ -99,7 +99,7 @@ void randr_init()
         XRRSelectInput(xctx.dpy, RootWindow(xctx.dpy, DefaultScreen(xctx.dpy)), RRScreenChangeNotifyMask);
 }
 
-void randr_update()
+void randr_update(void)
 {
         if (randr_major_version < 1
             || (randr_major_version == 1 && randr_minor_version < 5)) {
@@ -148,7 +148,7 @@ void screen_check_event(XEvent event)
                 randr_update();
 }
 
-void xinerama_update()
+void xinerama_update(void)
 {
         int n;
         XineramaScreenInfo *info = XineramaQueryScreens(xctx.dpy, &n);
@@ -172,7 +172,7 @@ void xinerama_update()
         XFree(info);
 }
 
-void screen_update_fallback()
+void screen_update_fallback(void)
 {
         alloc_screen_ar(1);
 
@@ -190,7 +190,7 @@ void screen_update_fallback()
  * Select the screen on which the Window
  * should be displayed.
  */
-screen_info *get_active_screen()
+screen_info *get_active_screen(void)
 {
         int ret = 0;
         if (settings.monitor > 0 && settings.monitor < screens_len) {

src/x11/screen.h

@@ -21,10 +21,10 @@ typedef struct _screen_info {
         dimension_t dim;
 } screen_info;
 
-void init_screens();
+void init_screens(void);
 void screen_check_event(XEvent event);
 
-screen_info *get_active_screen();
+screen_info *get_active_screen(void);
 double get_dpi_for_screen(screen_info *scr);
 
 #endif

src/x11/x.c

@@ -773,7 +773,7 @@ static void setopacity(Window win, unsigned long opacity)
 /*
  * Returns the modifier which is NumLock.
  */
-static KeySym x_numlock_mod()
+static KeySym x_numlock_mod(void)
 {
         static KeyCode nl = 0;
         KeySym sym = 0;
@@ -1199,7 +1199,7 @@ void x_win_show(void)
 /*
  * Hide the window and ungrab unused keyboard_shortcuts
  */
-void x_win_hide()
+void x_win_hide(void)
 {
         x_shortcut_ungrab(&settings.close_ks);
         x_shortcut_ungrab(&settings.close_all_ks);