From 16fcbc9db9dbe0af2b077b86755b34063b8a5b03 Mon Sep 17 00:00:00 2001 From: Benedikt Heine Date: Fri, 1 Mar 2019 13:00:11 +0100 Subject: [PATCH] Use @retval in codedocs --- HACKING.md | 2 ++ src/dbus.c | 3 ++- src/icon.h | 14 ++++++++------ src/markup.c | 3 ++- src/menu.h | 1 + src/queues.c | 11 ++++++----- src/queues.h | 11 ++++++----- src/x11/screen.h | 6 ++++-- 8 files changed, 31 insertions(+), 20 deletions(-) diff --git a/HACKING.md b/HACKING.md index 7f5ee0d..68beb27 100644 --- a/HACKING.md +++ b/HACKING.md @@ -6,6 +6,8 @@ - Comment system is held similar to JavaDoc - Use `@param` to describe all input parameters + - Use `@return` to describe the output value + - Use `@retval` to describe special return values (like `NULL`) - 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 diff --git a/src/dbus.c b/src/dbus.c index e4f098e..75c29ca 100644 --- a/src/dbus.c +++ b/src/dbus.c @@ -461,7 +461,8 @@ static void dbus_cb_name_acquired(GDBusConnection *connection, * @param name The place to report the name to, if not required set to NULL * @param vendor The place to report the vendor to, if not required set to NULL * - * @returns `true` on success, otherwise `false` + * @retval true: on success + * @retval false: Any error happened */ static bool dbus_get_fdn_daemon_info(GDBusConnection *connection, guint *pid, diff --git a/src/icon.h b/src/icon.h index 5e03bb3..37cbea0 100644 --- a/src/icon.h +++ b/src/icon.h @@ -23,7 +23,8 @@ GdkPixbuf *icon_pixbuf_scale(GdkPixbuf *pixbuf); * * @param filename A string representing a readable file path * - * @return an instance of `GdkPixbuf` or `NULL` if file does not exist + * @return an instance of `GdkPixbuf` + * @retval NULL: file does not exist, not readable, etc.. */ GdkPixbuf *get_pixbuf_from_file(const char *filename); @@ -33,7 +34,8 @@ GdkPixbuf *get_pixbuf_from_file(const char *filename); * or an icon name, which then gets searched for in the * settings.icon_path * - * @return an instance of `GdkPixbuf` or `NULL` if not found + * @return an instance of `GdkPixbuf` + * @retval NULL: file does not exist, not readable, etc.. */ GdkPixbuf *get_pixbuf_from_icon(const char *iconname); @@ -47,8 +49,8 @@ GdkPixbuf *get_pixbuf_from_icon(const char *iconname); * get searched in the folders of the icon_path setting. * @param id (necessary) A unique identifier of the returned pixbuf. Only filled, * if the return value is non-NULL. - * @return a pixbuf representing name's image. - * If an invalid path given, it will return NULL. + * @return an instance of `GdkPixbuf`, representing the name's image + * @retval NULL: Invalid path given */ GdkPixbuf *icon_get_for_name(const char *name, char **id); @@ -61,8 +63,8 @@ GdkPixbuf *icon_get_for_name(const char *name, char **id); * like described in the notification spec. * @param id (necessary) A unique identifier of the returned pixbuf. * Only filled, if the return value is non-NULL. - * @return a pixbuf representing name's image. - * If an invalid GVariant is passed, it will return NULL. + * @return an instance of `GdkPixbuf` derived from the GVariant + * @retval NULL: GVariant parameter nulled, invalid or in wrong format */ GdkPixbuf *icon_get_for_data(GVariant *data, char **id); diff --git a/src/markup.c b/src/markup.c index 8877138..72a46c7 100644 --- a/src/markup.c +++ b/src/markup.c @@ -236,7 +236,8 @@ char *markup_strip(char *str) * Determine if an & character pointed to by \p str is a markup & entity or * part of the text * - * @return true if it's an entity otherwise false + * @retval true: \p str is an entity + * @retval false: It's no valid entity */ static bool markup_is_entity(const char *str) { diff --git a/src/menu.h b/src/menu.h index c58ed4d..ec42ca2 100644 --- a/src/menu.h +++ b/src/menu.h @@ -7,6 +7,7 @@ * * @param to_match (nullable) String to extract URLs * @return a string of urls separated by '\n' + * @retval NULL: No URLs found */ char *extract_urls(const char *to_match); diff --git a/src/queues.c b/src/queues.c index dcbb4e0..6458063 100644 --- a/src/queues.c +++ b/src/queues.c @@ -127,7 +127,8 @@ static bool queues_notification_is_ready(const struct notification *n, struct du * * @param n the notification to check * @param status the current status of dunst - * @returns true, if the notification is timed out, otherwise false + * @retval true: the notification is timed out + * @retval false: otherwise */ static bool queues_notification_is_finished(struct notification *n, struct dunst_status status) { @@ -206,8 +207,8 @@ int queues_notification_insert(struct notification *n) /** * Replaces duplicate notification and stacks it * - * @return true, if notification got stacked - * @return false, if notification did not get stacked + * @retval true: notification got stacked + * @retval false: notification did not get stacked */ static bool queues_stack_duplicate(struct notification *n) { @@ -245,8 +246,8 @@ static bool queues_stack_duplicate(struct notification *n) /** * Replaces the first notification of the same stack_tag * - * @return true, if notification got stacked - * @return false, if notification did not get stacked + * @retval true: notification got stacked + * @retval false: notification did not get stacked */ static bool queues_stack_by_tag(struct notification *new) { diff --git a/src/queues.h b/src/queues.h index 92d5156..463d5dc 100644 --- a/src/queues.h +++ b/src/queues.h @@ -29,7 +29,8 @@ const GList *queues_get_displayed(void); /** * Get the highest notification in line * - * @return a notification or NULL, if waiting is empty + * @returns the first notification in waiting + * @retval NULL: waiting is empty */ const struct notification *queues_get_head_waiting(void); @@ -61,8 +62,8 @@ unsigned int queues_length_history(void); * - 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` + * @returns The new value of `n->id` + * @retval 0: the notification was dismissed and freed */ int queues_notification_insert(struct notification *n); @@ -73,8 +74,8 @@ int queues_notification_insert(struct notification *n); * * @param new replacement for the old notification * - * @return true, if a matching notification has been found and is replaced - * @return false, else + * @retval true: a matching notification has been found and is replaced + * @retval false: otherwise */ bool queues_notification_replace_id(struct notification *new); diff --git a/src/x11/screen.h b/src/x11/screen.h index 13b9c44..864c230 100644 --- a/src/x11/screen.h +++ b/src/x11/screen.h @@ -29,7 +29,8 @@ double get_dpi_for_screen(struct screen_info *scr); * @see window_is_fullscreen() * @see get_focused_window() * - * @return `true` if the focused window is in fullscreen mode + * @retval true: the focused window is in fullscreen mode + * @retval false: otherwise */ bool have_fullscreen_window(void); @@ -37,7 +38,8 @@ bool have_fullscreen_window(void); * Check if window is in fullscreen mode * * @param window the x11 window object - * @return `true` if `window` is in fullscreen mode + * @retval true: \p window is in fullscreen mode + * @retval false: otherwise */ bool window_is_fullscreen(Window window);