diff --git a/.gitignore b/.gitignore index c3a8c84..68d723e 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ org.knopwob.dunst.service dunst.systemd.service dunstify test/test +docs/internal/html diff --git a/.travis.yml b/.travis.yml index cdea5b9..0db5b8e 100644 --- a/.travis.yml +++ b/.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 diff --git a/HACKING.md b/HACKING.md index ad488b6..7f5ee0d 100644 --- a/HACKING.md +++ b/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 diff --git a/Makefile b/Makefile index a874571..3f20568 100644 --- a/Makefile +++ b/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 diff --git a/docs/internal/Doxyfile b/docs/internal/Doxyfile new file mode 100644 index 0000000..f4ef014 --- /dev/null +++ b/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 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 94c0c7f..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 */ -const GList *queues_get_displayed() +/* see queues.h */ +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 - * 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,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); diff --git a/src/queues.h b/src/queues.h index dab452b..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(); +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_displayed(); -unsigned int queues_length_history(); +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) */ -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 - * @reason: The reason to close + * @param n (transfer full) The notification 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, - * 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); diff --git a/src/x11/screen.c b/src/x11/screen.c index 51bc230..070c1f1 100644 --- a/src/x11/screen.c +++ b/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_update(); -void xinerama_update(); -void screen_update_fallback(); +void randr_init(void); +void randr_update(void); +void xinerama_update(void); +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) { diff --git a/src/x11/screen.h b/src/x11/screen.h index 8b47142..ed71081 100644 --- a/src/x11/screen.h +++ b/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 diff --git a/src/x11/x.c b/src/x11/x.c index 2df610b..92942da 100644 --- a/src/x11/x.c +++ b/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);