Convert notification.[ch] into docstrings

src/notification.c

@@ -42,10 +42,7 @@ const char *enum_to_string_fullscreen(enum behavior_fullscreen in)
         }
 }
 
-/*
+/* see notification.h */
- * print a human readable representation
- * of the given notification to stdout.
- */
 void notification_print(notification *n)
 {
         //TODO: use logging info for this
@@ -89,10 +86,7 @@ void notification_print(notification *n)
         printf("}\n");
 }
 
-/*
+/* see notification.h */
- * Run the script associated with the
- * given notification.
- */
 void notification_run_script(notification *n)
 {
         if (!n->script || strlen(n->script) < 1)
@@ -150,10 +144,7 @@ const char *notification_urgency_to_string(const enum urgency urgency)
         }
 }
 
-/*
+/* see notification.h */
- * Helper function to compare two given
- * notifications.
- */
 int notification_cmp(const notification *a, const notification *b)
 {
         if (a->urgency != b->urgency) {
@@ -163,10 +154,7 @@ int notification_cmp(const notification *a, const notification *b)
         }
 }
 
-/*
+/* see notification.h */
- * Wrapper for notification_cmp to match glib's
- * compare functions signature.
- */
 int notification_cmp_data(const void *va, const void *vb, void *data)
 {
         notification *a = (notification *) va;
@@ -192,10 +180,7 @@ int notification_is_duplicate(const notification *a, const notification *b)
             && a->urgency == b->urgency;
 }
 
-/*
+/* see notification.h */
- * Free the actions element
- * @a: (nullable): Pointer to #Actions
- */
 void actions_free(Actions *a)
 {
         if (!a)
@@ -206,10 +191,7 @@ void actions_free(Actions *a)
         g_free(a);
 }
 
-/*
+/* see notification.h */
- * Free a #RawImage
- * @i: (nullable): pointer to #RawImage
- */
 void rawimage_free(RawImage *i)
 {
         if (!i)
@@ -219,9 +201,7 @@ void rawimage_free(RawImage *i)
         g_free(i);
 }
 
-/*
+/* see notification.h */
- * Free the memory used by the given notification.
- */
 void notification_free(notification *n)
 {
         assert(n != NULL);
@@ -244,14 +224,7 @@ void notification_free(notification *n)
         g_free(n);
 }
 
-/*
+/* see notification.h */
- * Replace the two chars where **needle points
- * with a quoted "replacement", according to the markup settings.
- *
- * The needle is a double pointer and gets updated upon return
- * to point to the first char, which occurs after replacement.
- *
- */
 void notification_replace_single_field(char **haystack,
                                        char **needle,
                                        const char *replacement,
@@ -275,14 +248,7 @@ void notification_replace_single_field(char **haystack,
         g_free(input);
 }
 
-/*
+/* see notification.h */
- * Create notification struct and initialise all fields with either
- *  - the default (if it's not needed to be freed later)
- *  - its undefined representation (NULL, -1)
- *
- * This function is guaranteed to return a valid pointer.
- * @Returns: The generated notification
- */
 notification *notification_create(void)
 {
         notification *n = g_malloc0(sizeof(notification));
@@ -305,12 +271,7 @@ notification *notification_create(void)
         return n;
 }
 
-/*
+/* see notification.h */
- * Sanitize values of notification, apply all matching rules
- * and generate derived fields.
- *
- * @n: the notification to sanitize
- */
 void notification_init(notification *n)
 {
         /* default to empty string to avoid further NULL faults */
@@ -558,11 +519,7 @@ void notification_update_text_to_render(notification *n)
         n->text_to_render = buf;
 }
 
-/*
+/* see notification.h */
- * If the notification has exactly one action, or one is marked as default,
- * invoke it. If there are multiple and no default, open the context menu. If
- * there are no actions, proceed similarly with urls.
- */
 void notification_do_action(notification *n)
 {
         if (n->actions) {

src/notification.h

@@ -84,21 +84,87 @@ typedef struct _notification {
         char *urls;           /**< urllist delimited by '\\n' */
 } notification;
 
+/**
+ * Create notification struct and initialise all fields with either
+ *  - the default (if it's not needed to be freed later)
+ *  - its undefined representation (NULL, -1)
+ *
+ * This function is guaranteed to return a valid pointer.
+ * @returns The generated notification
+ */
 notification *notification_create(void);
+
+/**
+ * Sanitize values of notification, apply all matching rules
+ * and generate derived fields.
+ *
+ * @param n: the notification to sanitize
+ */
 void notification_init(notification *n);
+
+/**
+ * Free the actions structure
+ *
+ * @param a (nullable): Pointer to #Actions
+ */
 void actions_free(Actions *a);
+
+/**
+ * Free a #RawImage
+ *
+ * @param i (nullable): pointer to #RawImage
+ */
 void rawimage_free(RawImage *i);
+
+/**
+ * Free the memory used by the given notification.
+ *
+ * @param n: pointer to #notification
+ */
 void notification_free(notification *n);
+
+/**
+ * Helper function to compare two given notifications.
+ */
 int notification_cmp(const notification *a, const notification *b);
+
+/**
+ * Wrapper for notification_cmp to match glib's
+ * compare functions signature.
+ */
 int notification_cmp_data(const void *va, const void *vb, void *data);
+
 int notification_is_duplicate(const notification *a, const notification *b);
+
+/**
+ * Run the script associated with the
+ * given notification.
+ */
 void notification_run_script(notification *n);
+/**
+ * print a human readable representation
+ * of the given notification to stdout.
+ */
 void notification_print(notification *n);
+
+/**
+ * Replace the two chars where **needle points
+ * with a quoted "replacement", according to the markup settings.
+ *
+ * The needle is a double pointer and gets updated upon return
+ * to point to the first char, which occurs after replacement.
+ */
 void notification_replace_single_field(char **haystack,
                                        char **needle,
                                        const char *replacement,
                                        enum markup_mode markup_mode);
 void notification_update_text_to_render(notification *n);
+
+/**
+ * If the notification has exactly one action, or one is marked as default,
+ * invoke it. If there are multiple and no default, open the context menu. If
+ * there are no actions, proceed similarly with urls.
+ */
 void notification_do_action(notification *n);
 
 const char *notification_urgency_to_string(const enum urgency urgency);