From 6aabe19fb4c8a3c92056b8b0bc5d079907e10503 Mon Sep 17 00:00:00 2001
From: apio <blobs.trading@gmail.com>
Date: Wed, 12 Oct 2022 11:51:32 +0200
Subject: [PATCH] libc: Document the functions in stdio.h

---
 libs/libc/include/stdio.h | 97 +++++++++++++++++++++++++++++----------
 1 file changed, 73 insertions(+), 24 deletions(-)

diff --git a/libs/libc/include/stdio.h b/libs/libc/include/stdio.h
index b6386353..d17b8edf 100644
--- a/libs/libc/include/stdio.h
+++ b/libs/libc/include/stdio.h
@@ -13,8 +13,8 @@ typedef struct
     int f_err;
 } FILE;
 
-extern FILE* __stderr;
-extern FILE* __stdout;
+extern FILE* __stderr; // The standard error stream.
+extern FILE* __stdout; // The standard output stream.
 #define stderr __stderr
 #define stdout __stdout
 
@@ -22,31 +22,80 @@ extern FILE* __stdout;
 extern "C"
 {
 #endif
-    int fclose(FILE*);
-    int fflush(FILE*);
-    FILE* fopen(const char*, const char*);
-    int fprintf(FILE*, const char*, ...);
-    size_t fread(void*, size_t, size_t, FILE*);
+
+    /* Closes the file handle stream. */
+    int fclose(FILE* stream);
+
+    /* Does not do anything for now, since buffered IO is not implemented yet. */
+    int fflush(FILE* stream);
+
+    /* Opens the file at pathname according to the mode string. Returns the file handle on success, or NULL on error. */
+    FILE* fopen(const char* pathname, const char* mode);
+
+    /* Writes formatted output according to the string format to the file stream. */
+    int fprintf(FILE* stream, const char* format, ...);
+
+    /* Reads nmemb items of size size from the file stream into buf. */
+    size_t fread(void* buf, size_t size, size_t nmemb, FILE* stream);
+
     int fseek(FILE*, long, int); // Not implemented.
     long ftell(FILE*);           // Not implemented.
-    size_t fwrite(const void*, size_t, size_t, FILE*);
-    int ferror(FILE*);
-    int feof(FILE*);
-    void clearerr(FILE*);
+
+    /* Writes nmemb items of size size from buf into the file stream. */
+    size_t fwrite(const void* buf, size_t size, size_t nmemb, FILE* stream);
+
+    /* Returns nonzero if the error flag in stream was set. */
+    int ferror(FILE* stream);
+
+    /* Returns nonzero if the end-of-file flag in stream was set. */
+    int feof(FILE* stream);
+
+    /* Clears the error and end-of-file flags from stream. */
+    void clearerr(FILE* stream);
+
     void setbuf(FILE*, char*); // Not implemented.
-    int vfprintf(FILE*, const char*, va_list);
-    int printf(const char*, ...);
-    int vprintf(const char*, va_list);
-    int sprintf(char*, const char*, ...);
-    int snprintf(char*, size_t, const char*, ...);
-    int vsprintf(char*, const char*, va_list);
-    int vsnprintf(char*, size_t, const char*, va_list);
-    int puts(const char*);
-    int fputs(const char*, FILE*);
-    int fputc(int, FILE*);
-    int putc(int, FILE*);
-    int putchar(int);
-    void perror(const char*);
+
+    /* Writes formatted output according to the string format to the file stream. */
+    int vfprintf(FILE* stream, const char* format, va_list ap);
+
+    /* Writes formatted output according to the string format to standard output. */
+    int printf(const char* format, ...);
+
+    /* Writes formatted output according to the string format to standard output. */
+    int vprintf(const char* format, va_list ap);
+
+    /* Writes formatted output according to the string format to the string str. This function is unsafe, use snprintf
+     * instead. */
+    int sprintf(char* str, const char* format, ...);
+
+    /* Writes at most max bytes of formatted output according to the string format to the string str.*/
+    int snprintf(char* str, size_t max, const char* format, ...);
+
+    /* Writes formatted output according to the string format to the string str. This function is unsafe, use vsnprintf
+     * instead. */
+    int vsprintf(char* str, const char* format, va_list ap);
+
+    /* Writes at most max bytes of formatted output according to the string format to the string str. */
+    int vsnprintf(char* str, size_t max, const char* format, va_list ap);
+
+    /* Writes the string str followed by a trailing newline to stdout. */
+    int puts(const char* str);
+
+    /* Writes the string str to the file stream. */
+    int fputs(const char* str, FILE* stream);
+
+    /* Writes the character c to the file stream. */
+    int fputc(int c, FILE* stream);
+
+    /* Writes the character c to the file stream. */
+    int putc(int c, FILE* stream);
+
+    /* Writes the character c to standard output. */
+    int putchar(int c);
+
+    /* Prints a message to standard error consisting of the string str followed by a colon and the string representation
+     * of the last error encountered during a call to a system or library function. */
+    void perror(const char* str);
 
 #ifdef __cplusplus
 }