Refine comments

Author: jserv

include/lib/libc.h

@@ -1,7 +1,15 @@
 #pragma once
 
+/* Compact C standard library
+ *
+ * Provides essential C library functions for embedded systems including
+ * string manipulation, memory management, character classification,
+ * and basic I/O operations.
+ */
+
 #include <hal.h>
 
+/* Basic Type Definitions */
 #ifndef NULL
 #define NULL ((void *) 0) /* Standard NULL definition */
 #endif
@@ -10,25 +18,31 @@ typedef _Bool bool;
 #define false ((bool) 0)
 #define true ((bool) 1)
 
-/* Character classification macros */
-#define isprint(c) (' ' <= (c) && (c) <= '~')
-#define isspace(c) ((c) == ' ' || (c) == '\t' || (c) == '\n' || (c) == '\r')
-#define isdigit(c) ('0' <= (c) && (c) <= '9')
-#define islower(c) ('a' <= (c) && (c) <= 'z')
-#define isupper(c) ('A' <= (c) && (c) <= 'Z')
-#define isalpha(c) (islower(c) || isupper(c))
-#define isalnum(c) (isalpha(c) || isdigit(c))
+/* Utility Macros */
 #define min(a, b) ((a) < (b) ? (a) : (b))
 #define max(a, b) ((a) > (b) ? (a) : (b))
 
-/* Endianness conversion macros (standard network to host byte order) */
+/* Character Classification Macros */
+#define isprint(c) (' ' <= (c) && (c) <= '~') /* Printable character */
+#define isspace(c) \
+    ((c) == ' ' || (c) == '\t' || (c) == '\n' || (c) == '\r') /* Whitespace */
+#define isdigit(c) ('0' <= (c) && (c) <= '9') /* Decimal digit */
+#define islower(c) ('a' <= (c) && (c) <= 'z') /* Lowercase letter */
+#define isupper(c) ('A' <= (c) && (c) <= 'Z') /* Uppercase letter */
+#define isalpha(c) (islower(c) || isupper(c)) /* Alphabetic character */
+#define isalnum(c) (isalpha(c) || isdigit(c)) /* Alphanumeric character */
+
+/* Endianness Conversion Macros */
 #if __BYTE_ORDER == __BIG_ENDIAN
+/* Big-endian: no conversion needed */
 #define htons(n) (n)
 #define ntohs(n) (n)
 #define htonl(n) (n)
 #define ntohl(n) (n)
 
 #else /* __LITTLE_ENDIAN */
+/* Little-endian: byte swapping required */
+
 /* 16-bit byte swap */
 #define htons(n) \
     (((((uint16_t) (n) & 0x00FF)) << 8) | (((uint16_t) (n) & 0xFF00) >> 8))
@@ -54,6 +68,7 @@ typedef _Bool bool;
          ? (x)                                                            \
          : (((uint64_t) htonl((uint32_t) ((x) & 0xFFFFFFFFULL))) << 32) | \
                htonl((uint32_t) (((x) >> 32) & 0xFFFFFFFFULL)))
+
 #define ntohll(x)                                                         \
     ((1 == ntohl(1))                                                      \
          ? (x)                                                            \
@@ -62,53 +77,76 @@ typedef _Bool bool;
 
 #endif /* __BYTE_ORDER */
 
-/* String manipulation functions */
+/* String Manipulation Functions */
+
+/* String copying and concatenation */
 char *strcpy(char *s1, const char *s2);
 char *strncpy(char *s1, const char *s2, int32_t n);
 char *strcat(char *s1, const char *s2);
 char *strncat(char *s1, const char *s2, int32_t n);
+
+/* String comparison */
 int32_t strcmp(const char *s1, const char *s2);
 int32_t strncmp(const char *s1, const char *s2, int32_t n);
+
+/* String searching */
 char *strstr(const char *s1, const char *s2);
-size_t strlen(const char *s1);
 char *strchr(const char *s1, int32_t c);
 char *strpbrk(const char *s1, const char *s2);
+
+/* String length */
+size_t strlen(const char *s1);
+
+/* String tokenization */
 char *strsep(char **pp, const char *delim);
 char *strtok(char *s, const char *delim);
 char *strtok_r(char *s, const char *delim, char **holder);
 
-/* Memory manipulation functions */
+/* Memory Manipulation Functions */
+
+/* Memory copying and moving */
 void *memcpy(void *dst, const void *src, uint32_t n);
 void *memmove(void *dst, const void *src, uint32_t n);
+
+/* Memory comparison and initialization */
 int32_t memcmp(const void *cs, const void *ct, uint32_t n);
 void *memset(void *s, int32_t c, uint32_t n);
+
+/* Mathematical Functions */
 int32_t abs(int32_t n); /* Absolute value */
 
-/* Character classification and conversion functions */
+/* String to Number Conversion */
 int32_t strtol(const char *s, char **end, int32_t base);
 int32_t atoi(const char *s);
 void itoa(int32_t i, char *s, int32_t base); /* Integer to ASCII conversion */
 
-/* Random number generation */
+/* Random Number Generation */
 
 #ifndef RAND_MAX
 #define RAND_MAX 32767U /* Default max value for random() */
 #endif
 
+/* Simple random number generator */
 int32_t random(void);
 void srand(uint32_t seed);
 
-/* POSIX-style opaque container for re-entrant random number generator state */
+/* POSIX-style re-entrant random number generator */
 struct random_data {
-    uint32_t state; /* state must never be zero */
+    uint32_t state; /* State must never be zero */
 };
 int random_r(struct random_data *buf, int32_t *result);
 
-/* Input/Output functions */
+/* Input/Output Functions */
+
+/* Character and string output */
 int32_t puts(const char *str);
+
+/* Character and string input */
 int getchar(void);
 char *gets(char *s);
 char *fgets(char *s, int n, void *f);
 char *getline(char *s);
+
+/* Formatted output */
 int32_t printf(const char *fmt, ...);
 int32_t sprintf(char *out, const char *fmt, ...);