Add doxygen docs for markup and utils files

src/markup.c

@@ -12,6 +12,10 @@
 #include "settings.h"
 #include "utils.h"
 
+/**
+ * Convert all HTML special symbols to HTML entities.
+ * @param str (nullable)
+ */
 static char *markup_quote(char *str)
 {
         if (!str)
@@ -26,6 +30,10 @@ static char *markup_quote(char *str)
         return str;
 }
 
+/**
+ * Convert all HTML special entities to their actual char.
+ * @param str (nullable)
+ */
 static char *markup_unquote(char *str)
 {
         if (!str)
@@ -40,6 +48,10 @@ static char *markup_unquote(char *str)
         return str;
 }
 
+/**
+ * Convert all HTML linebreak tags to a newline character
+ * @param str (nullable)
+ */
 static char *markup_br2nl(char *str)
 {
         if (!str)
@@ -51,13 +63,7 @@ static char *markup_br2nl(char *str)
         return str;
 }
 
-/*
+/* see markup.h */
- * Remove HTML hyperlinks of a string.
- *
- * @str: The string to replace a tags
- * @urls: (nullable): If any href-attributes found, an '\n' concatenated
- *        string of the URLs in format '[<text between tags>] <href>'
- */
 void markup_strip_a(char **str, char **urls)
 {
         assert(*str);
@@ -132,13 +138,7 @@ void markup_strip_a(char **str, char **urls)
         }
 }
 
-/*
+/* see markup.h */
- * Remove img-tags of a string. If alt attribute given, use this as replacement.
- *
- * @str: The string to replace img tags
- * @urls: (nullable): If any src-attributes found, an '\n' concatenated string of
- *        the URLs in format '[<alt>] <src>'
- */
 void markup_strip_img(char **str, char **urls)
 {
         const char *start;
@@ -221,18 +221,7 @@ void markup_strip_img(char **str, char **urls)
         }
 }
 
-/*
+/* see markup.h */
- * Strip any markup from text; turn it in to plain text.
- *
- * For well-formed markup, the following two commands should be
- * roughly equivalent:
- *
- *     out = markup_strip(in);
- *     pango_parse_markup(in, -1, 0, NULL, &out, NULL, NULL);
- *
- * However, `pango_parse_markup()` balks at invalid markup;
- * `markup_strip()` shouldn't care if there is invalid markup.
- */
 char *markup_strip(char *str)
 {
         if (!str)
@@ -321,10 +310,7 @@ static char *markup_escape_unsupported(char *str)
         return str;
 }
 
-/*
+/* see markup.h */
- * Transform the string in accordance with `markup_mode` and
- * `settings.ignore_newline`
- */
 char *markup_transform(char *str, enum markup_mode markup_mode)
 {
         if (!str)

src/markup.h

@@ -4,11 +4,42 @@
 
 #include "settings.h"
 
+/**
+ * Strip any markup from text; turn it in to plain text.
+ *
+ * For well-formed markup, the following two commands should be
+ * roughly equivalent:
+ *
+ *     out = markup_strip(in);
+ *     pango_parse_markup(in, -1, 0, NULL, &out, NULL, NULL);
+ *
+ * However, `pango_parse_markup()` balks at invalid markup;
+ * `markup_strip()` shouldn't care if there is invalid markup.
+ */
 char *markup_strip(char *str);
 
+/**
+ * Remove HTML hyperlinks of a string.
+ *
+ * @param str The string to replace a tags
+ * @param urls (nullable) If any href-attributes found, an `\n` concatenated
+ *        string of the URLs in format `[<text between tags>] <href>`
+ */
 void markup_strip_a(char **str, char **urls);
+
+/**
+ * Remove img-tags of a string. If alt attribute given, use this as replacement.
+ *
+ * @param str The string to replace img tags
+ * @param urls (nullable) If any src-attributes found, an `\n` concatenated string of
+ *        the URLs in format `[<alt>] <src>`
+ */
 void markup_strip_img(char **str, char **urls);
 
+/**
+ * Transform the string in accordance with `markup_mode` and
+ * `settings.ignore_newline`
+ */
 char *markup_transform(char *str, enum markup_mode markup_mode);
 
 #endif

src/utils.c

@@ -11,6 +11,7 @@
 
 #include "log.h"
 
+/* see utils.h */
 char *string_replace_char(char needle, char replacement, char *haystack)
 {
         if (!haystack)
@@ -22,6 +23,7 @@ char *string_replace_char(char needle, char replacement, char *haystack)
         return haystack;
 }
 
+/* see utils.h */
 char *string_replace_at(char *buf, int pos, int len, const char *repl)
 {
         assert(buf);
@@ -51,6 +53,7 @@ char *string_replace_at(char *buf, int pos, int len, const char *repl)
         return tmp;
 }
 
+/* see utils.h */
 char *string_replace_all(const char *needle, const char *replacement, char *haystack)
 {
         if (!haystack)
@@ -78,6 +81,7 @@ char *string_replace_all(const char *needle, const char *replacement, char *hays
         return haystack;
 }
 
+/* see utils.h */
 char *string_append(char *a, const char *b, const char *sep)
 {
         if (STR_EMPTY(a)) {
@@ -95,7 +99,6 @@ char *string_append(char *a, const char *b, const char *sep)
         g_free(a);
 
         return new;
-
 }
 
 /* see utils.h */
@@ -115,6 +118,7 @@ char *string_strip_quotes(const char *value)
         return s;
 }
 
+/* see utils.h */
 void string_strip_delimited(char *str, char a, char b)
 {
         assert(str);
@@ -132,6 +136,7 @@ void string_strip_delimited(char *str, char a, char b)
         str[iwrite] = 0;
 }
 
+/* see utils.h */
 char *string_to_path(char *string)
 {
 
@@ -146,6 +151,7 @@ char *string_to_path(char *string)
         return string;
 }
 
+/* see utils.h */
 gint64 string_to_time(const char *string)
 {
         assert(string);

src/utils.h

@@ -16,19 +16,48 @@
 //! Test if string a and b are the same case-insensitively
 #define STR_CASEQ(a, b) (strcasecmp(a, b) == 0)
 
-/* replace all occurrences of the character needle with the character replacement in haystack */
+/**
+ * Replaces all occurrences of the char \p needle with the char \p replacement in \p haystack.
+ *
+ * Does not allocate a new string.
+ *
+ * @param needle The char to replace with replacement
+ * @param replacement The char which is the new one
+ * @param haystack (nullable) The string to replace
+ *
+ * @returns The exact value of the haystack paramater (to allow nesting)
+ */
 char *string_replace_char(char needle, char replacement, char *haystack);
 
-/* replace all occurrences of needle with replacement in haystack */
+/**
-char *string_replace_all(const char *needle, const char *replacement, char *haystack);
+ * Replace a substring inside a string with another string.
-
+ *
-/* replace <len> characters with <repl> at position <pos> of the string <buf> */
+ * May reallocate memory. Free the result with `g_free`.
+ *
+ * @param buf The string to replace
+ * @param pos The position of the substring to replace
+ * @param len The length of the substring to replace
+ * @param repl The new contents of the substring.
+ */
 char *string_replace_at(char *buf, int pos, int len, const char *repl);
 
-char *string_append(char *a, const char *b, const char *sep);
+/**
+ * Replace all occurences of a substring.
+ *
+ * @param needle The substring to search
+ * @param replacement The substring to replace
+ * @param haystack (nullable) The string to search the substring for
+ */
+char *string_replace_all(const char *needle, const char *replacement, char *haystack);
 
-/* strip content between two delimiter characters (inplace) */
+/**
-void string_strip_delimited(char *str, char a, char b);
+ * Append \p b to string \p a. And concatenate both strings with \p concat, if both are non-empty.
+ *
+ * @param a (nullable) The left side of the string
+ * @param b (nullable) The right side of the string
+ * @param sep (nullable) The concatenator to concatenate if a and b given
+ */
+char *string_append(char *a, const char *b, const char *sep);
 
 /**
  * Strip quotes from a string. Won't touch inner quotes.
@@ -38,10 +67,32 @@ void string_strip_delimited(char *str, char a, char b);
  */
 char *string_strip_quotes(const char *value);
 
-/* replace tilde and path-specific values with its equivalents */
+/**
+ * Strip content between two delimiter characters
+ *
+ * @param str The string to operate in place
+ * @param a Starting delimiter
+ * @param b Ending delimiter
+ */
+void string_strip_delimited(char *str, char a, char b);
+
+/**
+ * Replace tilde and path-specific values with its equivalents
+ *
+ * The string gets invalidated. The new valid representation is the return value.
+ *
+ * @param string (nullable) The string to convert to a path.
+ * @returns The tilde-replaced string.
+ */
 char *string_to_path(char *string);
 
-/* convert time units (ms, s, m) to internal gint64 microseconds */
+/**
+ * Convert time units (ms, s, m) to the internal `gint64` microseconds format
+ *
+ * If no unit is given, 's' (seconds) is assumed by default.
+ *
+ * @param string The string to parse the time format from.
+ */
 gint64 string_to_time(const char *string);
 
 /**