improve utils folder documentation

src/utils/fs.h

@@ -1,26 +1,109 @@
 #ifndef UTILS_FS_H__
 #define UTILS_FS_H__
 
-
 #include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
 
-
 #define FS_SECTOR_SIZE      (512)
 
+/**
+ * @file fs.h
+ * @brief File system utility functions.
+ * @ingroup utils
+ */
 
-char *strip_fs_prefix (char *path);
-char *file_basename (char *path);
+/**
+ * @brief Strips the file system prefix from the given path.
+ *
+ * This function removes the file system prefix from the provided path.
+ *
+ * @param path The path from which to strip the prefix.
+ * @return A pointer to the path without the prefix.
+ */
+char *strip_fs_prefix(char *path);
 
-bool file_exists (char *path);
-int64_t file_get_size (char *path);
-bool file_allocate (char *path, size_t size);
-bool file_fill (char *path, uint8_t value);
-bool file_has_extensions (char *path, const char *extensions[]);
+/**
+ * @brief Gets the basename of the given path.
+ *
+ * This function returns the basename of the provided path.
+ *
+ * @param path The path from which to get the basename.
+ * @return A pointer to the basename of the path.
+ */
+char *file_basename(char *path);
 
-bool directory_exists (char *path);
-bool directory_create (char *path);
+/**
+ * @brief Checks if a file exists at the given path.
+ *
+ * This function checks if a file exists at the specified path.
+ *
+ * @param path The path to the file.
+ * @return true if the file exists, false otherwise.
+ */
+bool file_exists(char *path);
 
+/**
+ * @brief Gets the size of the file at the given path.
+ *
+ * This function returns the size of the file at the specified path.
+ *
+ * @param path The path to the file.
+ * @return The size of the file in bytes, or -1 if the file does not exist.
+ */
+int64_t file_get_size(char *path);
 
-#endif
+/**
+ * @brief Allocates a file of the specified size at the given path.
+ *
+ * This function creates a file of the specified size at the provided path.
+ *
+ * @param path The path to the file.
+ * @param size The size of the file to create.
+ * @return true if the file was successfully created, false otherwise.
+ */
+bool file_allocate(char *path, size_t size);
+
+/**
+ * @brief Fills a file with the specified value.
+ *
+ * This function fills the file at the given path with the specified value.
+ *
+ * @param path The path to the file.
+ * @param value The value to fill the file with.
+ * @return true if the file was successfully filled, false otherwise.
+ */
+bool file_fill(char *path, uint8_t value);
+
+/**
+ * @brief Checks if a file has one of the specified extensions.
+ *
+ * This function checks if the file at the given path has one of the specified extensions.
+ *
+ * @param path The path to the file.
+ * @param extensions An array of extensions to check.
+ * @return true if the file has one of the specified extensions, false otherwise.
+ */
+bool file_has_extensions(char *path, const char *extensions[]);
+
+/**
+ * @brief Checks if a directory exists at the given path.
+ *
+ * This function checks if a directory exists at the specified path.
+ *
+ * @param path The path to the directory.
+ * @return true if the directory exists, false otherwise.
+ */
+bool directory_exists(char *path);
+
+/**
+ * @brief Creates a directory at the given path.
+ *
+ * This function creates a directory at the specified path.
+ *
+ * @param path The path to the directory.
+ * @return true if the directory was successfully created, false otherwise.
+ */
+bool directory_create(char *path);
+
+#endif // UTILS_FS_H__

src/utils/utils.h

@@ -1,14 +1,63 @@
 #ifndef UTILS_H__
 #define UTILS_H__
 
+/**
+ * @file utils.h
+ * @brief Utility macros and functions.
+ * @ingroup utils
+ */
 
-#define	ALIGN(x, a)     (((x) + ((typeof(x))(a) - 1)) & ~((typeof(x))(a) - 1))
+/**
+ * @brief Aligns a value to the specified alignment.
+ *
+ * This macro aligns the given value `x` to the specified alignment `a`.
+ *
+ * @param x The value to align.
+ * @param a The alignment boundary.
+ * @return The aligned value.
+ */
+#define ALIGN(x, a)     (((x) + ((typeof(x))(a) - 1)) & ~((typeof(x))(a) - 1))
 
+/**
+ * @brief Returns the maximum of two values.
+ *
+ * This macro returns the maximum of the two provided values `a` and `b`.
+ *
+ * @param a The first value.
+ * @param b The second value.
+ * @return The maximum of `a` and `b`.
+ */
 #define MAX(a,b)        ({ typeof(a) _a = a; typeof(b) _b = b; _a > _b ? _a : _b; })
+
+/**
+ * @brief Returns the minimum of two values.
+ *
+ * This macro returns the minimum of the two provided values `a` and `b`.
+ *
+ * @param a The first value.
+ * @param b The second value.
+ * @return The minimum of `a` and `b`.
+ */
 #define MIN(a,b)        ({ typeof(a) _a = a; typeof(b) _b = b; _a < _b ? _a : _b; })
 
+/**
+ * @brief Converts a value to kilobytes.
+ *
+ * This macro converts the given value `x` to kilobytes.
+ *
+ * @param x The value to convert.
+ * @return The value in kilobytes.
+ */
 #define KiB(x)          ((x) * 1024)
+
+/**
+ * @brief Converts a value to megabytes.
+ *
+ * This macro converts the given value `x` to megabytes.
+ *
+ * @param x The value to convert.
+ * @return The value in megabytes.
+ */
 #define MiB(x)          ((x) * 1024 * 1024)
 
-
-#endif
+#endif // UTILS_H__