Refine comments

Author: jserv

include/private/error.h

@@ -1,42 +1,55 @@
 #pragma once
 
+/* Centralizes all error codes used throughout the kernel. Error codes use
+ * automatic enumeration starting from -16383 to avoid conflicts with POSIX
+ * errno values. Each subsystem has its own logical grouping for easier
+ * debugging and maintenance.
+ */
+
 enum {
-    ERR_OK = 0,
-    ERR_FAIL = -1,
-
-    /* Scheduler / task management */
-    ERR_NO_TASKS = -16383,
-    ERR_KCB_ALLOC,
-    ERR_TCB_ALLOC,
-    ERR_STACK_ALLOC,
-    ERR_TASK_CANT_REMOVE,
-    ERR_TASK_NOT_FOUND,
-    ERR_TASK_CANT_SUSPEND,
-    ERR_TASK_CANT_RESUME,
-    ERR_TASK_INVALID_PRIO,
-    ERR_TASK_INVALID_ENTRY,
-    ERR_TASK_BUSY,
-    ERR_NOT_OWNER,
-
-    /* Stack guard */
-    ERR_STACK_CHECK,
-
-    /* IPC / synchronization */
-    ERR_PIPE_ALLOC,
-    ERR_PIPE_DEALLOC,
-    ERR_SEM_ALLOC,
-    ERR_SEM_DEALLOC,
-    ERR_SEM_OPERATION,
-    ERR_MQ_NOTEMPTY,
-    ERR_TIMEOUT,
-
-    /* must remain the last entry */
-    ERR_UNKNOWN
+    /* Success and Generic Errors */
+    ERR_OK = 0,    /* Operation completed successfully */
+    ERR_FAIL = -1, /* Generic failure */
+
+    /* Task Management and Scheduler Errors (auto-numbered from -16383) */
+    ERR_NO_TASKS = -16383,  /* No tasks available for scheduling */
+    ERR_KCB_ALLOC,          /* Kernel Control Block allocation failed */
+    ERR_TCB_ALLOC,          /* Task Control Block allocation failed */
+    ERR_STACK_ALLOC,        /* Task stack allocation failed */
+    ERR_TASK_CANT_REMOVE,   /* Task cannot be removed (e.g., self-remove) */
+    ERR_TASK_NOT_FOUND,     /* Task ID not found in system */
+    ERR_TASK_CANT_SUSPEND,  /* Task cannot be suspended */
+    ERR_TASK_CANT_RESUME,   /* Task cannot be resumed */
+    ERR_TASK_INVALID_PRIO,  /* Invalid task priority specified */
+    ERR_TASK_INVALID_ENTRY, /* Invalid task entry point */
+    ERR_TASK_BUSY,          /* Task is busy or in wrong state */
+    ERR_NOT_OWNER,          /* Operation requires ownership */
+
+    /* Memory Protection Errors */
+    ERR_STACK_CHECK, /* Stack overflow or corruption detected */
+
+    /* IPC and Synchronization Errors */
+    ERR_PIPE_ALLOC,    /* Pipe allocation failed */
+    ERR_PIPE_DEALLOC,  /* Pipe deallocation failed */
+    ERR_SEM_ALLOC,     /* Semaphore allocation failed */
+    ERR_SEM_DEALLOC,   /* Semaphore deallocation failed */
+    ERR_SEM_OPERATION, /* Semaphore operation failed */
+    ERR_MQ_NOTEMPTY,   /* Message queue is not empty */
+    ERR_TIMEOUT,       /* Operation timed out */
+
+    /* Sentinel - must remain the last entry */
+    ERR_UNKNOWN /* Unknown or unclassified error */
 };
 
+/* Error Code Description Structure
+ *
+ * Maps error codes to human-readable descriptions for debugging
+ * and error reporting purposes.
+ */
 struct error_code {
-    int32_t code;
-    char *const desc;
+    int32_t code;     /* The error code value */
+    char *const desc; /* Human-readable description */
 };
 
+/* Global error code lookup table */
 extern const struct error_code *const perror;

include/private/stdio.h

@@ -1,4 +1,4 @@
-/* Lightweight stdio hook layer.
+/* Lightweight stdio hook layer
  *
  * This header defines the interface for plugging in character-based I/O
  * routines. Kernel code uses these hooks ('_putchar', '_getchar', '_kbhit') to
@@ -9,12 +9,34 @@
 
 #pragma once
 
-/* Hook installers: Allow registration of device-specific I/O functions. */
+/* Hook Installation Functions
+ *
+ * These functions allow registration of device-specific I/O functions at
+ * runtime. Typically called during hardware initialization to connect the
+ * kernel I/O system to actual hardware drivers.
+ */
+
+/* Install stdout hook for character output */
 void _stdout_install(int (*hook)(int));
+
+/* Install stdin hook for character input */
 void _stdin_install(int (*hook)(void));
+
+/* Install polling hook for input readiness check */
 void _stdpoll_install(int (*hook)(void));
 
-/* Provide a consistent interface to the installed hooks. */
-int _putchar(int c); /* Blocking single-byte output. */
-int _getchar(void);  /* Blocking single-byte input (busy-wait). */
-int _kbhit(void);    /* Non-blocking poll for input readiness */
+/* Hook Interface Functions
+ *
+ * These functions provide a consistent interface to the installed hooks,
+ * dispatching to registered implementations or default stubs if no hooks
+ * have been installed.
+ */
+
+/* Blocking single-byte output */
+int _putchar(int c);
+
+/* Blocking single-byte input (busy-wait) */
+int _getchar(void);
+
+/* Non-blocking poll for input readiness */
+int _kbhit(void);

include/private/utils.h

@@ -1,22 +1,53 @@
 #pragma once
 
+/* Utility Macros and Functions
+ *
+ * Provides essential utility macros and inline functions used throughout
+ * the kernel for optimization, alignment, power-of-2 operations, and
+ * compile-time analysis hints.
+ */
+
 #include <lib/libc.h>
 
+/* Compiler Optimization Hints
+ *
+ * Branch prediction hints help the compiler and processor optimize for
+ * the most common code paths.
+ */
 #define unlikely(x) __builtin_expect(!!(x), 0)
 #define likely(x) __builtin_expect(!!(x), 1)
 
-#define UNUSED __attribute__((unused))
+/* Compiler Attributes */
+#define UNUSED __attribute__((unused)) /* Suppress unused warnings */
+
+/* Array and Memory Utilities */
 
+/* Calculate number of elements in a statically allocated array */
 #define ARRAY_SIZE(a) (sizeof(a) / sizeof(*(a)))
 
-/* Align pointer forward to the next 4-byte boundary */
+/* Align pointer forward to the next 4-byte boundary
+ * Essential for maintaining alignment requirements on RISC-V
+ */
 #define ALIGN4(x) ((((uint32_t) (x) + 3u) >> 2) << 2)
 
+/* Power-of-2 Utility Functions
+ *
+ * Efficient bit manipulation functions for power-of-2 operations,
+ * commonly used for buffer sizing and memory allocation.
+ */
+
+/* Check if a value is a power of 2
+ * Uses bit trick: power of 2 has only one bit set, so (x & (x-1)) == 0
+ */
 static inline bool ispowerof2(uint32_t x)
 {
     return x && !(x & (x - 1));
 }
 
+/* Round up to the next power of 2
+ * Uses bit manipulation to efficiently find the next power of 2
+ * greater than or equal to the input value
+ */
 static inline uint32_t nextpowerof2(uint32_t x)
 {
     x--;