improve comment blocks at the headers of .c and .h files

Doxyfile

@@ -829,8 +829,11 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ./kernel ./kernel/device ./kernel/lib ./kernel/core \
-                         ./kernel/proc ./kernel/fs ./kernel/test
+INPUT                  = ./kernel ./kernel/device/display \
+                         ./kernel/device/keyboard ./kernel/device/storage \
+                         ./kernel/base ./kernel/sys \
+                         ./kernel/proc ./kernel/fs ./kernel/mm \
+                         ./libc ./userspace
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

kernel/base/hash.c

@@ -1,3 +1,19 @@
+/**-----------------------------------------------------------------------------
+
+ @file    hash.c
+ @brief   Implementation of a simple hash table
+ @details
+ @verbatim
+
+  This file contains the implementation of a simple hash table used within
+  the HanOS kernel. It includes functions for initializing the hash table,
+  searching for a key, inserting a key-value pair, and deleting a key.
+  The hash table uses open addressing for collision resolution.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #include <stdbool.h>
 
 #include <libc/stdio.h>

kernel/base/hash.h

@@ -1,3 +1,20 @@
+/**-----------------------------------------------------------------------------
+
+ @file    hash.h
+ @brief   Hash table definitions
+ @details
+ @verbatim
+
+  This file contains the type definitions and function declarations for the
+  hash table implementation used within the HanOS kernel. It includes the
+  structure definitions for hash table items and the hash table itself,
+  as well as the function prototypes for initializing, searching, inserting,
+  and deleting entries in the hash table.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #pragma once
 
 #define HT_DEFAULT_ARRAY_SIZE       128

kernel/base/image.c

@@ -1,3 +1,19 @@
+/**-----------------------------------------------------------------------------
+
+ @file    image.c
+ @brief   Implementation of image handling functions
+ @details
+ @verbatim
+
+  This file contains the implementation of functions for handling images within
+  the HanOS kernel. It includes the function for loading BMP images from a file
+  into an image structure. The BMP loading function reads the file, parses the
+  BMP header, and extracts the image data for use within the kernel.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #include <libc/string.h>
 
 #include <fs/vfs.h>

kernel/base/image.h

@@ -1,3 +1,19 @@
+/**-----------------------------------------------------------------------------
+
+ @file    image.h
+ @brief   Image handling definitions
+ @details
+ @verbatim
+
+  This file contains the type definitions and function declarations for image
+  handling within the HanOS kernel. It includes the structure definition for
+  representing an image and a function prototype for loading a BMP image from
+  a file.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #pragma once
 
 #include <stdbool.h>

kernel/base/klib.h

@@ -1,8 +1,7 @@
 /**-----------------------------------------------------------------------------
 
  @file    klib.h
- @brief   Definition of fundamental data structures, macros and functions for
-          the kernel
+ @brief   Definition of fundamental data structures, macros and functions
  @details
  @verbatim
 

kernel/device/display/edid.h

@@ -1,3 +1,22 @@
+/**-----------------------------------------------------------------------------
+
+ @file    edid.h
+ @brief   EDID (Extended Display Identification Data) definitions
+ @details
+ @verbatim
+
+  This file contains the type definitions related to EDID (Extended Display
+  Identification Data) used within the HanOS kernel. The EDID data structure
+  provides detailed information about a display device's capabilities. This
+  includes the manufacturer ID, serial number, week and year of manufacture,
+  EDID version and revision, video input type, display size, gamma factor,
+  power management features, chromaticity coordinates, established timings,
+  standard timings, and detailed timings.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #pragma once
 
 typedef struct [[gnu::packed]] {

kernel/device/display/gfx.c

@@ -1,3 +1,21 @@
+/**-----------------------------------------------------------------------------
+
+ @file    gfx.c
+ @brief   Implementation of graphics device handling
+ @details
+ @verbatim
+
+  This file contains the implementation of functions for handling graphics
+  devices within the HanOS kernel. It includes functions for initializing PCI
+  graphics devices, configuring graphics translation tables (GTT), managing
+  graphics memory, and enabling specific graphics features. It also includes
+  functions for entering and exiting force wake states and for allocating
+  graphics memory objects.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #include <3rd-party/boot/limine.h>
 #include <stdint.h>
 #include <sys/cpu.h>

kernel/device/display/gfx.h

@@ -1,3 +1,21 @@
+/**-----------------------------------------------------------------------------
+
+ @file    gfx.h
+ @brief   Graphics device handling definitions
+ @details
+ @verbatim
+
+  This file contains the type definitions and function declarations for handling
+  graphics devices within the HanOS kernel. It includes structures for
+  representing PCI graphics devices, graphics translation tables (GTT), graphics
+  objects, and memory ranges. Additionally, it provides function prototypes for
+  initializing and starting the graphics system, as well as macros for
+  interacting with memory-mapped I/O registers of the graphics device.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #pragma once
 
 typedef struct {

kernel/device/display/gfx_reg.h

@@ -1,3 +1,20 @@
+/**-----------------------------------------------------------------------------
+
+ @file    gfx_reg.h
+ @brief   Graphics device register definitions
+ @details
+ @verbatim
+
+  This file contains the definitions of various registers and constants used
+  for handling graphics devices within the HanOS kernel. It includes bit masks
+  and shifts for manipulating register values, as well as addresses for memory
+  mapped I/O registers related to graphics memory management, GTT (Graphics
+  Translation Table), and display control.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #pragma once
 
 #define MASKED_ENABLE(x)                (((x) << 16) | (x))

kernel/device/keyboard/keycode.h

@@ -1,3 +1,20 @@
+/**-----------------------------------------------------------------------------
+
+ @file    keycode.h
+ @brief   Keycode definitions for keyboard driver
+ @details
+ @verbatim
+
+  This file contains the keycode definitions and function declarations used in
+  the HanOS keyboard driver. It defines constants for common keyboard keys such
+  as arrow keys, backspace, caps lock, enter, control, shift, and tab. It also
+  declares a function for converting scancode inputs into ASCII characters
+  considering the shift and caps lock states.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #pragma once
 
 #define KB_ARROW_UP     72

kernel/device/storage/ata.c

@@ -1,3 +1,21 @@
+/**-----------------------------------------------------------------------------
+
+ @file    ata.c
+ @brief   Implementation of ATA (Advanced Technology Attachment) device handling
+ @details
+ @verbatim
+
+  This file contains the implementation of functions for handling ATA devices
+  within the HanOS kernel. It includes functions for initializing and detecting
+  ATA and ATAPI devices, performing PIO read and write operations, and reading
+  partition maps. Additionally, it provides utility functions for interacting
+  with ATA registers and handling device-specific operations such as soft
+  resets and polling for device status.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #include <libc/string.h>
 
 #include <sys/pci.h>

kernel/device/storage/ata.h

@@ -1,3 +1,22 @@
+/**-----------------------------------------------------------------------------
+
+ @file    ata.h
+ @brief   ATA (Advanced Technology Attachment) definitions
+ @details
+ @verbatim
+
+  This file contains the type definitions, constants, and function declarations
+  for handling ATA devices within the HanOS kernel. It includes definitions for
+  ATA status and error codes, command codes, identification fields, and
+  register addresses. It also defines structures for representing IDE channels,
+  devices, partitions, and ATA identity information, as well as function
+  prototypes for initializing ATA devices and performing PIO read and write
+  operations.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #pragma once
 
 #define ATA_SR_BSY              0x80

kernel/fs/filebase.c

@@ -76,8 +76,8 @@ vfs_node_desc_t *vfs_handle_to_fd(vfs_handle_t handle, const char *func)
 {
     task_t *t = sched_get_current_task();
     if (t != NULL) {
-        vfs_node_desc_t* nd = (vfs_node_desc_t*)ht_search(&(t->open_files_table), handle);
-        if (nd != NULL) return nd;
+        vfs_node_desc_t* fd = (vfs_node_desc_t*)ht_search(&(t->open_files_table), handle);
+        if (fd != NULL) return fd;
         klogw("VFS: %s() cannot locate %d (0x%x) in file list of task %d\n",
               func, handle, handle, t->tid);
     }

kernel/fs/pipefs.c

@@ -1,3 +1,20 @@
+/**-----------------------------------------------------------------------------
+
+ @file    pipefs.c
+ @brief   Implementation of PipeFS functions
+ @details
+ @verbatim
+
+  This file contains the implementation of the PipeFS, a simple filesystem for
+  handling pipe files within the HanOS Kernel. It provides functions for
+  mounting, creating, removing, opening, reading, and writing pipe files. The
+  PipeFS is designed to facilitate inter-process communication by using pipes
+  as a means to transfer data between processes.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #include <libc/string.h>
 #include <libc/errno.h>
 #include <libc/stdio.h>

kernel/fs/pipefs.h

@@ -1,3 +1,19 @@
+/**-----------------------------------------------------------------------------
+
+ @file    pipefs.h
+ @brief   Definition of PipeFS related data structures and functions
+ @details
+ @verbatim
+
+  PipeFS is a simple file system designed to handle pipe files within the HanOS
+  Kernel. It provides basic file system operations such as mounting, creating,
+  removing, opening, reading, and writing pipe files. This file defines the
+  necessary data structures and function prototypes used by PipeFS.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #pragma once
 
 #include <fs/vfs.h>

kernel/fs/ramfs.c

@@ -1,3 +1,19 @@
+/**-----------------------------------------------------------------------------
+
+ @file    ramfs.c
+ @brief   Implementation of RAMFS functions
+ @details
+ @verbatim
+
+  This file contains the implementation of the RAMFS, a simple filesystem that
+  resides entirely in memory. It provides functions for mounting, creating,
+  removing, opening, reading, writing, and syncing files. The RAMFS is designed
+  to facilitate fast in-memory file operations.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #include <libc/string.h>
 
 #include <fs/ramfs.h>

kernel/fs/ramfs.h

@@ -1,3 +1,19 @@
+/**-----------------------------------------------------------------------------
+
+ @file    ramfs.h
+ @brief   Definition of RAMFS related data structures and functions
+ @details
+ @verbatim
+
+  RAMFS is a simple filesystem that resides entirely in memory. It provides
+  basic file system operations such as mounting, creating, removing, opening,
+  reading, writing, and syncing files. This file defines the necessary data
+  structures and function prototypes used by RAMFS.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #pragma once
 
 #include <fs/vfs.h>

kernel/fs/ttyfs.c

@@ -1,3 +1,19 @@
+/**-----------------------------------------------------------------------------
+
+ @file    ttyfs.c
+ @brief   Implementation of TTYFS functions
+ @details
+ @verbatim
+
+  This file contains the implementation of the TTYFS (Teletypewriter Filesystem),
+  a simple filesystem designed to handle TTY files within the HanOS Kernel. It
+  provides functions for mounting, creating, opening, reading, writing, and
+  syncing TTY files, as well as handling IO control operations.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #include <libc/string.h>
 #include <libc/errno.h>
 #include <libc/stdio.h>

kernel/fs/ttyfs.h

@@ -1,3 +1,20 @@
+/**-----------------------------------------------------------------------------
+
+ @file    ttyfs.h
+ @brief   Definition of TTYFS related data structures and functions
+ @details
+ @verbatim
+
+  TTYFS is a simple filesystem designed to handle TTY (teletypewriter) files
+  within the HanOS Kernel. It provides basic file system operations such as
+  mounting, creating, opening, reading, writing, and syncing TTY files. This
+  file defines the necessary data structures and function prototypes used by
+  TTYFS.
+
+ @endverbatim
+
+ **-----------------------------------------------------------------------------
+ */
 #pragma once
 
 #include <fs/vfs.h>