libc: Update headers with more comments

libs/libc/include/assert.h

@@ -18,7 +18,7 @@ extern "C"
 #ifdef NDEBUG
 #define assert(expr) (void)0
 #else
-#define assert(expr) (bool)(expr) || __assertion_failed(__FILE__, __LINE__, __FUNCTION__, #expr)
+#define assert(expr) (bool)(expr) || __assertion_failed(__FILE__, __LINE__, __FUNCTION__, #expr) // Verify a condition.
 #endif
 
 #endif

libs/libc/include/bits/macros.h

@@ -4,6 +4,7 @@
 #define __lc_noreturn __attribute__((noreturn))
 #define __lc_align(n) __attribute__((aligned(n)))
 #define __lc_deprecated(msg) __attribute__((deprecated(msg)))
+#define __lc_is_deprecated __attribute__((deprecated))
 #define __lc_unreachable __builtin_unreachable
 #define __lc_used __attribute__((used))
 

libs/libc/include/ctype.h

@@ -1,6 +1,8 @@
 #ifndef _CTYPE_H
 #define _CTYPE_H
 
+#include <bits/macros.h>
+
 #ifdef __cplusplus
 extern "C"
 {
@@ -51,6 +53,10 @@ extern "C"
     /* Returns the uppercase form of the specified character. */
     int toupper(int c);
 
+    /* Returns the character c, truncated to fit in the ASCII character set. This function should not be used, as it
+     * will convert accented letters into random characters. */
+    __lc_is_deprecated int toascii(int c);
+
 #ifdef __cplusplus
 }
 #endif

libs/libc/include/dirent.h

@@ -4,6 +4,7 @@
 #include <luna/os-limits.h>
 #include <sys/types.h>
 
+/* An entry in a directory. */
 struct dirent
 {
     ino_t d_ino;
@@ -13,6 +14,7 @@ struct dirent
     char d_name[NAME_MAX];
 };
 
+/* A stream representing a directory. */
 typedef struct
 {
     int d_dirfd;

libs/libc/include/stdio.h

@@ -7,10 +7,11 @@
 
 #include <bits/seek.h>
 
-#define FOPEN_MAX 32
-#define BUFSIZ 32
+#define FOPEN_MAX 32      // Maximum number of files that can be simultaneously opened with fopen().
+#define BUFSIZ 32         // Standard buffer size.
 #define FILENAME_MAX 1024 // Dummy value, we don't have a limit for filenames right now.
 
+/* A stream representing a file. */
 typedef struct
 {
     int f_fd;
@@ -25,17 +26,18 @@ typedef struct
 extern FILE* stderr;
 extern FILE* stdout;
 extern FILE* stdin;
-#define stdin stdin
-#define stdout stdout
-#define stderr stderr
 
-#define EOF -1
+#define stdin stdin   // The standard input stream.
+#define stdout stdout // The standard output stream.
+#define stderr stderr // The standard error stream.
 
-#define _IONBF 0
-#define _IOLBF 1
-#define _IOFBF 2
+#define EOF -1 // End of file.
 
-typedef off_t fpos_t;
+#define _IONBF 0 // Not buffered.
+#define _IOLBF 1 // Line buffered.
+#define _IOFBF 2 // Fully buffered.
+
+typedef off_t fpos_t; // An offset into a file.
 
 #ifdef __cplusplus
 extern "C"

libs/libc/include/stdlib.h

@@ -5,23 +5,26 @@
 #include <limits.h>
 #include <stddef.h>
 
-#define EXIT_SUCCESS 0
-#define EXIT_FAILURE 1
+#define EXIT_SUCCESS 0 // Value to use when calling exit() to represent successful execution.
+#define EXIT_FAILURE 1 // Value to use when calling exit() to represent failed execution.
 
-#define RAND_MAX INT_MAX
+#define RAND_MAX INT_MAX // Maximum number returned by rand().
 
+// Return type for an integer division.
 typedef struct
 {
     int quot;
     int rem;
 } div_t;
 
+// Return type for a long integer division.
 typedef struct
 {
     long quot;
     long rem;
 } ldiv_t;
 
+// Return type for a long integer division.
 typedef struct
 {
     long long quot;

libs/libc/include/sys/types.h

@@ -19,4 +19,10 @@ typedef unsigned short mode_t;
 /* The type of a filesystem inode. */
 typedef unsigned long ino_t;
 
+/* Value representing a time unit since the start of the current program. */
+typedef long int clock_t;
+
+/* Value representing time in seconds. */
+typedef long int time_t;
+
 #endif

libs/libc/include/time.h

@@ -2,10 +2,9 @@
 #define _TIME_H
 
 #include <stddef.h>
+#include <sys/types.h>
 
-typedef long int clock_t;
-typedef long int time_t;
-
+// Structure representing broken-down time.
 struct tm
 {
     int tm_sec;
@@ -22,7 +21,7 @@ struct tm
     const char* tm_zone;
 };
 
-#define CLOCKS_PER_SEC 1000
+#define CLOCKS_PER_SEC 1000 // Number of clock_t per second.
 
 #ifdef __cplusplus
 extern "C"

libs/libc/src/ctype.cpp

@@ -78,4 +78,9 @@ extern "C"
         if (islower(c)) return c & 0x5f;
         return c;
     }
+
+    int toascii(int c)
+    {
+        return c & 0x7f;
+    }
 }