Better docs and structure

task.c

@@ -1,6 +1,21 @@
+/*
+ * task.c – Cooperative multitasking: PCB pool, scheduler, yield/exit.
+ *
+ * Task 0 is the kernel/shell thread (uses the boot stack).
+ * Additional tasks are created with task_create(), which allocates a
+ * stack from the PMM and sets up a fake context-switch frame so that
+ * context_switch() can "return" into a trampoline that calls the real
+ * entry function.
+ *
+ * Scheduling is purely cooperative: tasks must call task_yield() to
+ * let others run.  The scheduler uses round-robin selection among
+ * READY tasks.
+ */
+
 #include "task.h"
 #include "memory.h"
 
+/* Null-safe print helper used throughout the kernel. */
 #define SAFE_PRINT(Boot, ...)                           \
     do {                                                \
         if ((Boot) != NULL && (Boot)->print != NULL) {  \
@@ -9,14 +24,14 @@
     } while (0)
 
 /* ================================================================
- *  Task / Process Control Block pool
+ *  Module state
  * ================================================================ */
 
-static Task     tasks[TASK_MAX];
+static Task     tasks[TASK_MAX];   /* PCB pool (static array)         */
 static Task    *current_task = NULL;
-static UINT32   next_pid = 0;
-static BootInfo *task_boot = NULL;
-static BOOLEAN  task_ready = FALSE;
+static UINT32   next_pid     = 0;
+static BootInfo *task_boot   = NULL;
+static BOOLEAN  task_ready   = FALSE;
 
 /* Forward declaration */
 static void task_trampoline(void);
@@ -25,6 +40,7 @@ static void task_trampoline(void);
  *  Helpers
  * ---------------------------------------------------------------- */
 
+/* Copy a wide string with a maximum length (including NUL). */
 static void wstrcpy16(CHAR16 *dst, const CHAR16 *src, UINTN max)
 {
     UINTN i = 0;
@@ -39,6 +55,10 @@ static void wstrcpy16(CHAR16 *dst, const CHAR16 *src, UINTN max)
  *  Initialisation – make the current (kernel) thread task 0
  * ---------------------------------------------------------------- */
 
+/*
+ * Initialise the scheduler: clear all PCB slots and register the
+ * currently running kernel thread as task 0.
+ */
 void task_init(BootInfo *Boot)
 {
     UINTN i;