Improve documentation

src/common.c

@@ -70,6 +70,11 @@ struct curl_data_t
 
 static size_t _data_callback(void* ptr, size_t size, size_t nmemb, void* data);
 
+/**
+ * Frees the memory allocated for a gchar* string.
+ *
+ * @param str Pointer to the gchar* string to be freed. If NULL, no action is taken.
+ */
 void
 auto_free_gchar(gchar** str)
 {
@@ -78,6 +83,11 @@ auto_free_gchar(gchar** str)
     g_free(*str);
 }
 
+/**
+ * Frees the memory allocated for a guchar* string.
+ *
+ * @param str Pointer to the guchar* string to be freed. If NULL, no action is taken.
+ */
 void
 auto_free_guchar(guchar** ptr)
 {
@@ -87,6 +97,11 @@ auto_free_guchar(guchar** ptr)
     g_free(*ptr);
 }
 
+/**
+ * Frees the memory allocated for a gchar** string array.
+ *
+ * @param args Pointer to the gchar** string array to be freed. If NULL, no action is taken.
+ */
 void
 auto_free_gcharv(gchar*** args)
 {
@@ -95,6 +110,11 @@ auto_free_gcharv(gchar*** args)
     g_strfreev(*args);
 }
 
+/**
+ * Frees the memory allocated for a char* string.
+ *
+ * @param str Pointer to the char* string to be freed. If NULL, no action is taken.
+ */
 void
 auto_free_char(char** str)
 {
@@ -134,6 +154,18 @@ copy_file(const char* const sourcepath, const char* const targetpath, const gboo
     return success;
 }
 
+/**
+ * @brief Replaces all occurrences of a substring with a replacement in a string.
+ *
+ * @param string      The input string to perform replacement on.
+ * @param substr      The substring to be replaced.
+ * @param replacement The replacement string.
+ * @return            The modified string with replacements, or NULL on failure.
+ *
+ * @note Remember to free returned value using `auto_char` or `free()` when it is no longer needed.
+ * @note If 'string' is NULL, the function returns NULL.
+ * @note If 'substr' or 'replacement' is NULL or an empty string, a duplicate of 'string' is returned.
+ */
 char*
 str_replace(const char* string, const char* substr,
             const char* replacement)
@@ -496,6 +528,18 @@ call_external(gchar** argv)
     return is_successful;
 }
 
+/**
+ * @brief Formats an argument vector for calling an external command with placeholders.
+ *
+ * This function constructs an argument vector (argv) based on the provided template string, replacing placeholders ("%u" and "%p") with the provided URL and filename, respectively.
+ *
+ * @param template  The template string with placeholders.
+ * @param url       The URL to replace "%u" (or NULL to skip).
+ * @param filename  The filename to replace "%p" (or NULL to skip).
+ * @return          The constructed argument vector (argv) as a null-terminated array of strings.
+ *
+ * @note Remember to free the returned argument vector using `auto_gcharv` or `g_strfreev()`.
+ */
 gchar**
 format_call_external_argv(const char* template, const char* url, const char* filename)
 {
@@ -548,6 +592,14 @@ _has_directory_suffix(const char* path)
             || g_str_has_suffix(path, G_DIR_SEPARATOR_S));
 }
 
+/**
+ * @brief Extracts the basename from a given URL.
+ *
+ * @param url The URL to extract the basename from.
+ * @return The extracted basename or a default name ("index") if the basename has a directory suffix.
+ *
+ * @note The returned string must be freed by the caller using `auto_free` or `free()`.
+ */
 char*
 basename_from_url(const char* url)
 {
@@ -564,6 +616,14 @@ basename_from_url(const char* url)
     return strdup(basename);
 }
 
+/**
+ * Expands the provided path by resolving special characters like '~' and 'file://'.
+ *
+ * @param path The path to expand.
+ * @return The expanded path.
+ *
+ * @note Remember to free the returned value using `auto_gchar` or `g_free()`.
+ */
 gchar*
 get_expanded_path(const char* path)
 {
@@ -577,6 +637,15 @@ get_expanded_path(const char* path)
     }
 }
 
+/**
+ * Generates a unique filename based on the provided URL and path.
+ *
+ * @param url The URL to derive the basename from.
+ * @param path The path to prepend to the generated filename. If NULL, the current directory is used.
+ * @return A unique filename combining the path and derived basename from the URL.
+ *
+ * @note Remember to free the returned value using `auto_gchar` or `g_free()`.
+ */
 gchar*
 unique_filename_from_url(const char* url, const char* path)
 {

src/common.h

@@ -54,16 +54,41 @@
 #define PROF_STRINGIFY(n)  PROF_STRINGIFY_(n)
 
 void auto_free_gchar(gchar** str);
-#define auto_gchar __attribute__((__cleanup__(auto_free_gchar)))
-void auto_free_gcharv(gchar*** args);
-#define auto_gcharv __attribute__((__cleanup__(auto_free_gcharv)))
-void auto_free_char(char** str);
-#define auto_char __attribute__((__cleanup__(auto_free_char)))
+
 /**
- * Frees the memory allocated for a guchar* string.
+ * Macro for automatically freeing a gchar* string when it goes out of scope.
  *
- * @param str Pointer to the guchar* string to be freed. If NULL, no action is taken.
+ * Example usage:
+ * ```
+ * auto_gchar gchar* myString = g_strdup("Hello, world!");
+ * ```
  */
+#define auto_gchar __attribute__((__cleanup__(auto_free_gchar)))
+
+void auto_free_gcharv(gchar*** args);
+
+/**
+ * Macro for automatically freeing a gchar** string array when it goes out of scope.
+ *
+ * Example usage:
+ * ```
+ * auto_gcharv gchar** stringArray = g_strsplit("Hello, world!", " ", -1);
+ * ```
+ */
+#define auto_gcharv __attribute__((__cleanup__(auto_free_gcharv)))
+
+void auto_free_char(char** str);
+
+/**
+ * Macro for automatically freeing a char* string when it goes out of scope.
+ *
+ * Example usage:
+ * ```
+ * auto_char char* myString = strdup("Hello, world!");
+ * ```
+ */
+#define auto_char __attribute__((__cleanup__(auto_free_char)))
+
 void auto_free_guchar(guchar** str);
 
 /**

src/config/files.c

@@ -155,8 +155,7 @@ files_get_config_path(const char* const config_base)
  * @param location The location (directory or file) to append to the project base path.
  * @return The full path obtained by appending the location to the project base path.
  *
- * @note The returned value must be freed using g_free when it is no longer needed
- *       to prevent memory leaks.
+ * @note Remember to free returned string using `auto_gchar` or `g_free()` when it is no longer needed to prevent memory leaks.
  */
 gchar*
 files_get_data_path(const char* const location)

src/config/preferences.c

@@ -517,6 +517,14 @@ prefs_set_boolean(preference_t pref, gboolean value)
     g_key_file_set_boolean(prefs, group, key, value);
 }
 
+/**
+ * @brief Retrieves a string preference value.
+ *
+ * @param pref The preference identifier.
+ * @return The string preference value or `NULL` if not found.
+ *
+ * @note Remember to free the returned string using `auto_gchar` or `g_free()`.
+ */
 gchar*
 prefs_get_string(preference_t pref)
 {
@@ -537,6 +545,15 @@ prefs_get_string(preference_t pref)
     }
 }
 
+/**
+ * @brief Retrieves a localized string preference value.
+ *
+ * @param pref   The preference to retrieve the value for.
+ * @param locale The option to consider.
+ * @return       Returns the value associated with pref translated in the given locale if available.
+ *
+ * @note Remember to free the returned string using `auto_gchar` or `g_free()`.
+ */
 gchar*
 prefs_get_string_with_locale(preference_t pref, gchar* locale)
 {
@@ -562,6 +579,12 @@ prefs_get_string_with_locale(preference_t pref, gchar* locale)
     return result;
 }
 
+/**
+ * @brief Sets or deletes a string value for the given preference in the preference file.
+ *
+ * @param pref      The preference to set the value for.
+ * @param new_value The new string value to set. Pass NULL to remove the key.
+ */
 void
 prefs_set_string(preference_t pref, gchar* new_value)
 {