feat: kernel: Documentation improvements and specs addition.

Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>

10 files changed, 31 insertions, 23 deletions

diff --git a/src/kernel/CFKit/Property.h b/src/kernel/CFKit/Property.h
index 1dab7b71..f2b58c1d 100644
--- a/src/kernel/CFKit/Property.h
+++ b/src/kernel/CFKit/Property.h
@@ -20,7 +20,7 @@ namespace Kernel::CF {
 using PropertyId = UIntPtr;
 
 /// @brief Kernel property class.
-/// @example /prop/smp_max or /prop/kern_ver
+/// @note /prop/smp_max or /prop/kern_ver are properties.
 class Property {
  public:
   Property();
diff --git a/src/kernel/CFKit/Utils.h b/src/kernel/CFKit/Utils.h
index 247ad5fb..41dc5a0d 100644
--- a/src/kernel/CFKit/Utils.h
+++ b/src/kernel/CFKit/Utils.h
@@ -4,7 +4,7 @@
 #include <KernelKit/MSDOS.h>
 #include <KernelKit/PE.h>
 
-/// @brief CFKit
+/// @brief CFKit namespace.
 namespace Kernel::CF {
 /// @brief Finds the PE header inside the blob.
 inline auto ldr_find_exec_header(DosHeaderPtr ptrDos) -> LDR_EXEC_HEADER_PTR {
@@ -14,7 +14,7 @@ inline auto ldr_find_exec_header(DosHeaderPtr ptrDos) -> LDR_EXEC_HEADER_PTR {
 
   if (ptrDos->eMagic[1] != kMagMz1) return nullptr;
 
-#ifdef __NE_AMD64__
+#if defined(__NE_AMD64__)
   return (LDR_EXEC_HEADER_PTR) (VoidPtr) (&ptrDos->eLfanew + 1);
 #else
   return (LDR_EXEC_HEADER_PTR) (VoidPtr) (&ptrDos->eLfanew);
diff --git a/src/kernel/DmaKit/DmaPool.h b/src/kernel/DmaKit/DmaPool.h
index e20f8c69..9b7e6b82 100644
--- a/src/kernel/DmaKit/DmaPool.h
+++ b/src/kernel/DmaKit/DmaPool.h
@@ -26,8 +26,11 @@
 #define kNeDMABestAlign (8)
 
 namespace Kernel {
+
 /// @brief DMA pool base pointer, here we're sure that AHCI or whatever tricky standard sees it.
-inline UInt8*       kDmaPoolPtr = (UInt8*) kNeDMAPoolStart;
+inline UInt8* kDmaPoolPtr = (UInt8*) kNeDMAPoolStart;
+
+/// @brief DMA pool end pointer.
 inline const UInt8* kDmaPoolEnd = (UInt8*) (kNeDMAPoolStart + kNeDMAPoolSize);
 
 /***********************************************************************************/
@@ -98,4 +101,5 @@ inline Void rtl_dma_flush(VoidPtr ptr, SizeT size_buffer) {
     HAL::mm_memory_fence((VoidPtr) ((UInt8*) ptr + buf_idx));
   }
 }
+
 }  // namespace Kernel
diff --git a/src/kernel/KernelKit/HardwareThreadScheduler.h b/src/kernel/KernelKit/HardwareThreadScheduler.h
index 6493e550..ea74cc10 100644
--- a/src/kernel/KernelKit/HardwareThreadScheduler.h
+++ b/src/kernel/KernelKit/HardwareThreadScheduler.h
@@ -51,29 +51,29 @@ class HardwareThread final {
   NE_COPY_DEFAULT(HardwareThread)
 
  public:
-  operator bool();
+  explicit operator bool();
 
  public:
-  void Wake(const BOOL wakeup = false);
-  void Busy(const BOOL busy = false);
+  Void Wake(const BOOL wakeup = false);
+  Void Busy(const BOOL busy = false);
 
  public:
   BOOL Switch(HAL::StackFramePtr frame);
   BOOL IsWakeup();
 
  public:
-  HAL::StackFramePtr StackFrame();
-  ThreadKind&        Kind();
-  BOOL               IsBusy();
-  ThreadID&          ID();
+  HAL::StackFramePtr        StackFrame();
+  _Output const ThreadKind& Kind();
+  BOOL                      IsBusy();
+  _Output const ThreadID&   ID();
 
  private:
-  HAL::StackFramePtr fStack{nullptr};
+  HAL::StackFramePtr fStack{};
   ThreadKind         fKind{ThreadKind::kAPStandard};
-  ThreadID           fID{0};
+  ThreadID           fID{};
   Bool               fWakeup{NO};
   Bool               fBusy{NO};
-  UInt64             fPTime{0};
+  UInt64             fPTime{};
 
  private:
   friend class HardwareThreadScheduler;
diff --git a/src/kernel/KernelKit/UserProcessScheduler.h b/src/kernel/KernelKit/UserProcessScheduler.h
index 08788ba3..0ac7623e 100644
--- a/src/kernel/KernelKit/UserProcessScheduler.h
+++ b/src/kernel/KernelKit/UserProcessScheduler.h
@@ -141,7 +141,7 @@ class UserProcess final {
 
   /***********************************************************************************/
   ///! @brief Get the process's name
-  ///! @example 'C Runtime Library'
+  ///! @example process can be called 'C Runtime Library'.
   /***********************************************************************************/
   const Char* GetName();
 
diff --git a/src/kernel/src/ACPIFactoryInterface.cc b/src/kernel/src/ACPIFactoryInterface.cc
index 42819b7e..d94d661e 100644
--- a/src/kernel/src/ACPIFactoryInterface.cc
+++ b/src/kernel/src/ACPIFactoryInterface.cc
@@ -10,7 +10,8 @@
 #include <modules/ACPI/ACPIFactoryInterface.h>
 
 namespace Kernel {
-constexpr STATIC const auto kMinACPIVer = 1U;
+/// \note This has been incremented to version two, as NeKernel doesn't support 32-bit targets. See specs.
+constexpr STATIC const auto kMinACPIVer = 2U;
 
 /// @brief Finds a descriptor table inside ACPI XSDT.
 ErrorOr<voidPtr> ACPIFactoryInterface::Find(const Char* signature) {
diff --git a/src/kernel/src/HardwareThreadScheduler.cc b/src/kernel/src/HardwareThreadScheduler.cc
index d1adc490..d31a74fe 100644
--- a/src/kernel/src/HardwareThreadScheduler.cc
+++ b/src/kernel/src/HardwareThreadScheduler.cc
@@ -41,14 +41,14 @@ HardwareThread::~HardwareThread() = default;
 /***********************************************************************************/
 //! @brief returns the id of the thread.
 /***********************************************************************************/
-ThreadID& HardwareThread::ID() {
+_Output const ThreadID& HardwareThread::ID() {
   return fID;
 }
 
 /***********************************************************************************/
 //! @brief returns the kind of thread we have.
 /***********************************************************************************/
-ThreadKind& HardwareThread::Kind() {
+_Output const ThreadKind& HardwareThread::Kind() {
   return fKind;
 }
 
diff --git a/src/kernel/src/IFS.cc b/src/kernel/src/IFS.cc
index 4679b8a3..8dec93f2 100644
--- a/src/kernel/src/IFS.cc
+++ b/src/kernel/src/IFS.cc
@@ -9,9 +9,9 @@
 
 /*************************************************************
  *
- * File: IFS.cc
- * Purpose: Filesystem to mountpoint interface.
- * Date: 05/26/2025
+ * File: \file IFS.cc
+ * Purpose: \brief Filesystem to mountpoint interface.
+ * Date: \date 05/26/2025
  *
  * Copyright (C) 2024-2025, Amlal El Mahrouss, licensed under the Apache 2.0 license.
  *
@@ -27,7 +27,7 @@ namespace Kernel {
 /// @param Mnt mounted interface.
 /// @param DrvTrait drive info
 /// @param DrvIndex drive index.
-/// @return
+/// @return KPC status code from the IFS.
 Int32 fs_ifs_read(IMountpoint* Mnt, DriveTrait& DrvTrait, Int32 DrvIndex) {
   if (!Mnt) return kErrorDisk;
 
diff --git a/src/kernel/src/UserProcessScheduler.cc b/src/kernel/src/UserProcessScheduler.cc
index cf3c27e9..f2b7ac21 100644
--- a/src/kernel/src/UserProcessScheduler.cc
+++ b/src/kernel/src/UserProcessScheduler.cc
@@ -10,7 +10,7 @@
 /***********************************************************************************/
 /// @file UserProcessScheduler.cc
 /// @brief Unprivileged/Ring-3 process scheduler.
-/// @author Amlal El Mahrouss (amlal@nekernel.org)
+/// @author Amlal El Mahrouss (amlal at nekernel dot org)
 /***********************************************************************************/
 
 #include <ArchKit/ArchKit.h>
diff --git a/src/launch/src/CRuntimeZero.S b/src/launch/src/CRuntimeZero.S
index 4f983b46..6a6d3257 100644
--- a/src/launch/src/CRuntimeZero.S
+++ b/src/launch/src/CRuntimeZero.S
@@ -10,6 +10,9 @@
 .extern ThrExitMainThread
 .globl _NeMain
 
+/** 	This should not be touched unless there's a **really** valid reason to it.
+	\note This helps start the ne_launch program.
+*/
 _NeMain:
   push %rbp
   movq %rsp, %rbp