From a018dfd471d8742b90dcf526383a265787d1bf96 Mon Sep 17 00:00:00 2001
From: nub31 <oliverlhs@outlook.com>
Date: Sun, 7 Sep 2025 00:22:54 +0200
Subject: [PATCH] some lib docs

---
 src/lib/assert.h |  3 ++-
 src/lib/printf.c | 17 +++++++++++++++++
 src/lib/string.c |  8 ++++++++
 src/lib/string.h |  2 +-
 4 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/src/lib/assert.h b/src/lib/assert.h
index ac653cc..ab3b644 100644
--- a/src/lib/assert.h
+++ b/src/lib/assert.h
@@ -3,7 +3,8 @@
 #include <arch.h>
 #include <printf.h>
 
-// In arch code, make sure arch_api.panic and arch_api.console.putchar is set up befire calling
+// Make sure `arch_api.panic` and `arch_api.console.putchar` is intialized if calling from architecure-specific code.
+// Will be compiled out if `DEBUG` is not defined.
 static inline void assert(bool condition, const char* msg)
 {
 #if DEBUG
diff --git a/src/lib/printf.c b/src/lib/printf.c
index b385c7f..2469bb9 100644
--- a/src/lib/printf.c
+++ b/src/lib/printf.c
@@ -3,6 +3,23 @@
 #include <def.h>
 #include <string.h>
 
+// Make sure `arch_api.console.putchar` is intialized if calling from architecure-specific code.
+//
+// Supported formats:
+//     - `d`: i64     (decimal)
+//     - `u`: u64     (decimal)
+//     - `x`: u64     (hex)
+//     - `c`: char    (ascii)
+//     - `s`: char*   (ascii string)
+//
+// ```c
+// printf(
+//     "The answer is %d is located at offset %x in file %s",
+//      42,
+//      0x2000
+//      "hitchhiker.txt"
+// );
+// ```
 void printf(const char* fmt, ...)
 {
     va_list args;
diff --git a/src/lib/string.c b/src/lib/string.c
index f4d032e..e3fab34 100644
--- a/src/lib/string.c
+++ b/src/lib/string.c
@@ -25,6 +25,10 @@ void reverse(char* str, size_t length)
     }
 }
 
+// ```c
+// char buffer[21];
+// itoa64(-1234, buffer);
+// ```
 void itoa64(i64 value, char* buffer)
 {
     char temp[21];
@@ -75,6 +79,10 @@ void itoa64(i64 value, char* buffer)
     buffer[j] = '\0';
 }
 
+// ```c
+// char buffer[21];
+// uitoa64(1234, buffer);
+// ```
 void uitoa64(u64 value, char* buffer)
 {
     char temp[21];
diff --git a/src/lib/string.h b/src/lib/string.h
index 846d807..d576768 100644
--- a/src/lib/string.h
+++ b/src/lib/string.h
@@ -5,6 +5,6 @@
 int strcmp(const char* a, const char* b);
 void reverse(char* str, size_t length);
 
-void uitoa64(u64 value, char* buffer);
 void itoa64(i64 value, char* buffer);
+void uitoa64(u64 value, char* buffer);
 void uitoa64_hex(u64 value, char* buffer);
\ No newline at end of file