Add Comments on printf

apps/demo.c

@@ -22,4 +22,4 @@ void io_demo() {
 	printf("end of demo loop.\n");
 	printf("And heres what happnes with unknown formats:\n %a %b %% %f\n", 1, 2, 3, 4);	
 	printf("done. (press ^a then x to quit qemu)");
-}
\ No newline at end of file
+}

drivers/dbgu.c

@@ -76,4 +76,4 @@ sequence_io_status dbgu_read(uint len, byte* buff) {
 	else
 		out.err = 0;
 	return out;
-}
\ No newline at end of file
+}

interfaces.h

@@ -4,6 +4,11 @@
 #include "default.h"
 
 // Utilites, maybe move somewhere else
+/**
+ * Struct to hold the result of multiple sequential IO operations, as we don't have errno
+ * io: number of sucessfull io operations
+ * err: error on the (io+1)th operation or 0 if all requests were sucessfull
+ */
 typedef struct {
 	uint io;
 	int err;

libs/printf.c

@@ -18,6 +18,23 @@ sequence_io_status printf(char* format, ...) {
 		.err = 0
 	};
 	sequence_io_status hw_out;
+	/*
+	 * How this works:
+	 * format points at remainder of the format string,
+	 * cursor runs ahead and points at whatever is going to be formatted next.
+	 * 
+	 * the loop then explosts the fact that a format sting is a sequence of %?
+	 * with constant strings in between. Thus it loops as follows:
+	 * 
+	 * while format left:
+	 *   write constant string
+	 *   if format left:
+	 *     pop arg
+	 *     format arg
+	 *     write arg
+	 * end:
+	 *   free(args)
+	 */
 	while (*cursor) {
 		// run to the next '%'
 		for (cursor = format; *cursor && *cursor != '%'; ++cursor);
@@ -27,9 +44,9 @@ sequence_io_status printf(char* format, ...) {
 		if (out.err || !*cursor)
 			goto end;
 
-		++cursor;
+		++cursor; // cursor is at a '%' here, the foramt char is next.
 		switch (*cursor) {
-			case 0:
+			case 0: // format string ends on a '%', we're friendly and print it.
 				hw_out = dbgu_write(1, cursor - 1);
 				break;
 			case 'c':
@@ -50,6 +67,7 @@ sequence_io_status printf(char* format, ...) {
 			case 'x':
 				/* fall through */
 			case 'p':
+				// write the number into the buffer, back to front.
 				pos = 9;
 				for (u32 num = va_arg(args, u32); num; num >>= 4, --pos)
 					buff[pos] = lookuptable[num & 0xF];
@@ -67,4 +85,4 @@ sequence_io_status printf(char* format, ...) {
 end:
 	va_end(args);
 	return out;
-}
\ No newline at end of file
+}