Better docs and structure

kernel.c

@@ -1,3 +1,15 @@
+/*
+ * kernel.c – Kernel entry point and interactive shell loop.
+ *
+ * kmain() is called by the UEFI loader (main.c) after the ELF kernel
+ * has been mapped into memory.  It initialises subsystems (IDT, memory,
+ * tasks), prints a welcome banner, and enters an interactive read-
+ * eval-print loop that dispatches typed commands via commands.c.
+ *
+ * While waiting for keyboard input, the shell yields to the cooperative
+ * scheduler so that background tasks can make progress.
+ */
+
 #include <efi.h>
 
 #include "boot_info.h"
@@ -6,6 +18,7 @@
 #include "memory.h"
 #include "task.h"
 
+/* Null-safe print helper used throughout the kernel. */
 #define SAFE_PRINT(Boot, ...)                           \
     do {                                                \
         if ((Boot) != NULL && (Boot)->print != NULL) {  \
@@ -13,6 +26,10 @@
         }                                               \
     } while (0)
 
+/* ================================================================
+ *  Kernel entry point
+ * ================================================================ */
+
 void kmain(BootInfo *Boot)
 {
     EFI_INPUT_KEY Key;
@@ -37,11 +54,12 @@ void kmain(BootInfo *Boot)
         }
     }
 
+    /* ---- Subsystem initialisation ---- */
     idt_init(Boot);
     memory_init(Boot);
     task_init(Boot);
 
-    SAFE_PRINT(Boot, L"================================================\n\r");
+    /* ---- Welcome banner ---- */
     SAFE_PRINT(Boot, L"  Welcome to Simple UEFI Operating System!\n\r");
     SAFE_PRINT(Boot, L"================================================\n\r");
     SAFE_PRINT(Boot, L"\n\r");
@@ -69,7 +87,7 @@ void kmain(BootInfo *Boot)
     SAFE_PRINT(Boot, L"\n\r");
     SAFE_PRINT(Boot, L"Type 'help' for a list of commands.\n\r\n\r");
 
-    // Simple line buffer
+    /* ---- Interactive shell loop ---- */
     CHAR16 line[128];
     UINTN len = 0;
 
@@ -100,21 +118,22 @@ void kmain(BootInfo *Boot)
         read_errors = 0;
 
         if (Key.UnicodeChar == L'\r' || Key.UnicodeChar == L'\n') {
-            // Enter pressed: terminate string and handle
+            /* Enter pressed: execute the buffered command */
             line[len] = L'\0';
             SAFE_PRINT(Boot, L"\n\r");
             execute_command(Boot, line);
 
-            // Reset for next command
+            /* Reset for next command */
             len = 0;
             SAFE_PRINT(Boot, L"-> ");
         } else if (Key.ScanCode == 0x08 || Key.UnicodeChar == L'\b' || Key.UnicodeChar == 0x7F) {
-            // Backspace (ScanCode 0x08 is backspace in UEFI)
+            /* Backspace */
             if (len > 0) {
                 len--;
                 SAFE_PRINT(Boot, L"\b \b");
             }
         } else if (Key.UnicodeChar >= 32 && Key.UnicodeChar < 127) {
+            /* Printable ASCII */
             if (len < (sizeof(line) / sizeof(line[0]) - 1)) {
                 line[len++] = Key.UnicodeChar;
                 SAFE_PRINT(Boot, L"%c", Key.UnicodeChar);