Merge pull request #610 from bebehei/docs-retval

Use @retval in codedocs

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

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,

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);
 

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)
 {

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);
 

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)
 {
@@ -209,8 +210,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)
 {
@@ -248,8 +249,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)
 {

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);
 

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);