docs: comment header function

vmm/handler.h

+#ifndef _STATES_H_
 #define _STATES_H_
-#ifdef _STATES_H_
 
 #include <stdint.h>
 #include <linux/kvm.h>
@@ -12,12 +12,47 @@ extern state_handler_t const STATE_HANDLERS[];
 
 // --- FUNCITON ---
 
+/**
+ * @brief Handles the virtual machine halt (HLT) instruction exit.
+ *
+ * @param run        Pointer to the `kvm_run` structure, holding VM exit information.
+ * @param shared_buf Buffer shared between the host and guest.
+ * @param mem        Pointer to the VM's memory.
+ */
 void handle_halt(struct kvm_run *run, uint8_t *shared_buf, uint8_t *mem);
 
+/**
+ * @brief Handles the I/O port access (PMIO) exit from the virtual machine.
+ *
+ * This function processes writes to I/O ports, and if necessary, triggers state transitions or executes hypercalls.
+ *
+ * @param run        Pointer to the `kvm_run` structure, holding VM exit information.
+ * @param shared_buf Buffer shared between the host and guest.
+ * @param mem        Pointer to the VM's memory.
+ */
 void handle_pmio(struct kvm_run *run, uint8_t *shared_buf, uint8_t *mem);
 
+/**
+ * @brief Handles the memory-mapped I/O (MMIO) exit from the virtual machine.
+ *
+ * This function processes MMIO writes and triggers state transitions as needed based on the address and value.
+ *
+ * @param run        Pointer to the `kvm_run` structure, holding VM exit information.
+ * @param shared_buf Buffer shared between the host and guest.
+ * @param mem        Pointer to the VM's memory.
+ */
 void handle_mmio(struct kvm_run *run, uint8_t *shared_buf, uint8_t *mem);
 
+/**
+ * @brief Handles hypercalls issued by the virtual machine.
+ *
+ * This function processes hypercalls based on the provided code and invokes the appropriate handler (e.g., 
+ * for console output, timer setup, graphics initialization or ...).
+ *
+ * @param code       Hypercall code indicating the operation to be performed.
+ * @param shared_buf Buffer shared between the host and guest.
+ * @param mem        Pointer to the VM's memory.
+ */
 void handle_hypercall(uint32_t code, uint8_t *shared_buf, uint8_t *mem);
 
 #endif // _STATES_H_

vmm/operation.h

+#ifndef _OPERATION_H_
 #define _OPERATION_H_
-#ifdef _OPERATION_H_
 
 #include <stdint.h>
 #include <unistd.h>
@@ -11,10 +11,10 @@
 
 typedef enum {
 
-    OP_WRITE_EQUAL,
-    OP_WRITE_STORE,
-    OP_READ_INJECT,
-    OP_EMUL_END,
+    OP_WRITE_EQUAL,  // Perform a write operation and check if the written value matches the expected value
+    OP_WRITE_STORE,  // Store the written value into a specific location (used in callbacks)
+    OP_READ_INJECT,  // Inject a value into the guest from a specific address
+    OP_EMUL_END,     // End of the state machine, with an callback for completion
 } operation_t;
 
 typedef struct {
@@ -36,16 +36,46 @@ extern state_t STATE_VGA[];
 
 // --- FUNCITON ---
 
+/**
+ * @brief Callback function triggered when the console operation concludes.
+ *
+ * @param addr Address containing the console message to be printed.
+ */
 void op_callback_console_conclude(void *addr);
 
+/**
+ * @brief Callback function to store the timer value during the state machine execution.
+ *
+ * @param addr Address of the timer value to be stored.
+ */
 void op_callback_timer_store(void *addr);
 
+/**
+ * @brief Callback function to conclude the timer operation and set the sleep timer.
+ *
+ * @param addr Address of the timer parameters, or `NULL` to use previously stored values.
+ */
 void op_callback_timer_conclude(void *addr);
 
+/**
+ * @brief Callback function to store the width during graphics initialization.
+ *
+ * @param addr Address of the width value to be stored.
+ */
 void op_callback_gfx_init_store_w(void *addr);
 
+/**
+ * @brief Callback function to store the height during graphics initialization.
+ *
+ * @param addr Address of the height value to be stored.
+ */
 void op_callback_gfx_init_store_h(void *addr);
 
+/**
+ * @brief Callback function to conclude the graphics initialization process.
+ *
+ * @param addr Address of the graphics parameters, or `NULL` to use previously stored values.
+ */
 void op_callback_gfx_init_conclude(void *addr);
 
 #endif // _OPERATION_H_