Do a lot of doc work and refactor along the way

Yay! I finished commenting the code!

Signed-off-by: Gavin Howard <gavin@yzena.com>

1 files changed, 61 insertions, 0 deletions

diff --git a/src/file.c b/src/file.c
index 3de4ac0f..35a4647d 100644
--- a/src/file.c
+++ b/src/file.c
@@ -44,25 +44,42 @@
 #include <file.h>
 #include <vm.h>
 
+/**
+ * Translates an integer into a string.
+ * @param val  The value to translate.
+ * @param buf  The return parameter.
+ */
 static void bc_file_ultoa(unsigned long long val, char buf[BC_FILE_ULL_LENGTH])
 {
 	char buf2[BC_FILE_ULL_LENGTH];
 	size_t i, len;
 
+	// We need to make sure the entire thing is zeroed.
 	memset(buf2, 0, BC_FILE_ULL_LENGTH);
 
 	// The i = 1 is to ensure that there is a null byte at the end.
 	for (i = 1; val; ++i) {
+
 		unsigned long long mod = val % 10;
+
 		buf2[i] = ((char) mod) + '0';
 		val /= 10;
 	}
 
 	len = i;
 
+	// Since buf2 is reversed, reverse it into buf.
 	for (i = 0; i < len; ++i) buf[i] = buf2[len - i - 1];
 }
 
+/**
+ * Output to the file directly.
+ * @param fd   The file descriptor.
+ * @param buf  The buffer of data to output.
+ * @param n    The number of bytes to output.
+ * @return     A status indicating error or success. We could have a fatal I/O
+ *             error or EOF.
+ */
 static BcStatus bc_file_output(int fd, const char *buf, size_t n) {
 
 	size_t bytes = 0;
@@ -70,10 +87,13 @@ static BcStatus bc_file_output(int fd, const char *buf, size_t n) {
 
 	BC_SIG_TRYLOCK(lock);
 
+	// While the number of bytes written is less than intended...
 	while (bytes < n) {
 
+		// Write.
 		ssize_t written = write(fd, buf + bytes, n - bytes);
 
+		// Check for error and return, if any.
 		if (BC_ERR(written == -1))
 			return errno == EPIPE ? BC_STATUS_EOF : BC_STATUS_ERROR_FATAL;
 
@@ -89,28 +109,38 @@ BcStatus bc_file_flushErr(BcFile *restrict f, BcFlushType type)
 {
 	BcStatus s;
 
+	// If there is stuff to output...
 	if (f->len) {
 
 #if BC_ENABLE_HISTORY
+
+		// If history is enabled...
 		if (BC_TTY) {
+
+			// If we have been told to save the extras, and there *are*
+			// extras...
 			if (f->buf[f->len - 1] != '\n' &&
 			    (type == BC_FLUSH_SAVE_EXTRAS_CLEAR ||
 			     type == BC_FLUSH_SAVE_EXTRAS_NO_CLEAR))
 			{
 				size_t i;
 
+				// Look for the last newline.
 				for (i = f->len - 2; i < f->len && f->buf[i] != '\n'; --i);
 
 				i += 1;
 
+				// Save the extras.
 				bc_vec_string(&vm.history.extras, f->len - i, f->buf + i);
 			}
+			// Else clear the extras if told to.
 			else if (type >= BC_FLUSH_NO_EXTRAS_CLEAR) {
 				bc_vec_popAll(&vm.history.extras);
 			}
 		}
 #endif // BC_ENABLE_HISTORY
 
+		// Actually output.
 		s = bc_file_output(f->fd, f->buf, f->len);
 		f->len = 0;
 	}
@@ -123,12 +153,15 @@ void bc_file_flush(BcFile *restrict f, BcFlushType type) {
 
 	BcStatus s = bc_file_flushErr(f, type);
 
+	// If we have an error...
 	if (BC_ERR(s)) {
 
+		// For EOF, set it and jump.
 		if (s == BC_STATUS_EOF) {
 			vm.status = (sig_atomic_t) s;
 			BC_JMP;
 		}
+		// Blow up on fatal error. Okay, not blow up, just quit.
 		else bc_vm_fatalError(BC_ERR_FATAL_IO_ERR);
 	}
 }
@@ -136,11 +169,14 @@ void bc_file_flush(BcFile *restrict f, BcFlushType type) {
 void bc_file_write(BcFile *restrict f, BcFlushType type,
                    const char *buf, size_t n)
 {
+	// If we have enough to flush, do it.
 	if (n > f->cap - f->len) {
 		bc_file_flush(f, type);
 		assert(!f->len);
 	}
 
+	// If the output is large enough to flush by itself, just output it.
+	// Otherwise, put it into the buffer.
 	if (BC_UNLIKELY(n > f->cap - f->len)) bc_file_output(f->fd, buf, n);
 	else {
 		memcpy(f->buf + f->len, buf, n);
@@ -163,10 +199,18 @@ void bc_file_vprintf(BcFile *restrict f, const char *fmt, va_list args) {
 	const char *ptr = fmt;
 	char buf[BC_FILE_ULL_LENGTH];
 
+	// This is a poor man's printf(). While I could look up algorithms to make
+	// it as fast as possible, and should when I write the standard library for
+	// a new language, for bc, outputting is not the bottleneck. So we cheese it
+	// for now.
+
+	// Find each percent sign.
 	while ((percent = strchr(ptr, '%')) != NULL) {
 
 		char c;
 
+		// If the percent sign is not where we are, write what's inbetween to
+		// the buffer.
 		if (percent != ptr) {
 			size_t len = (size_t) (percent - ptr);
 			bc_file_write(f, bc_flush_none, ptr, len);
@@ -174,6 +218,8 @@ void bc_file_vprintf(BcFile *restrict f, const char *fmt, va_list args) {
 
 		c = percent[1];
 
+		// We only parse some format specifiers, the ones bc uses. If you add
+		// more, you need to make sure to add them here.
 		if (c == 'c') {
 
 			uchar uc = (uchar) va_arg(args, int);
@@ -187,15 +233,18 @@ void bc_file_vprintf(BcFile *restrict f, const char *fmt, va_list args) {
 			bc_file_puts(f, bc_flush_none, s);
 		}
 #if BC_DEBUG_CODE
+		// We only print signed integers in debug code.
 		else if (c == 'd') {
 
 			int d = va_arg(args, int);
 
+			// Take care of negative. Let's not worry about overflow.
 			if (d < 0) {
 				bc_file_putchar(f, bc_flush_none, '-');
 				d = -d;
 			}
 
+			// Either print 0 or translate and print.
 			if (!d) bc_file_putchar(f, bc_flush_none, '0');
 			else {
 				bc_file_ultoa((unsigned long long) d, buf);
@@ -207,11 +256,15 @@ void bc_file_vprintf(BcFile *restrict f, const char *fmt, va_list args) {
 
 			unsigned long long ull;
 
+			// These are the ones that it expects from here. Fortunately, all of
+			// these are unsigned types, so they can use the same code, more or
+			// less.
 			assert((c == 'l' || c == 'z') && percent[2] == 'u');
 
 			if (c == 'z') ull = (unsigned long long) va_arg(args, size_t);
 			else ull = (unsigned long long) va_arg(args, unsigned long);
 
+			// Either print 0 or translate and print.
 			if (!ull) bc_file_putchar(f, bc_flush_none, '0');
 			else {
 				bc_file_ultoa(ull, buf);
@@ -219,9 +272,12 @@ void bc_file_vprintf(BcFile *restrict f, const char *fmt, va_list args) {
 			}
 		}
 
+		// Increment to the next spot after the specifier.
 		ptr = percent + 2 + (c == 'l' || c == 'z');
 	}
 
+	// If we get here, there are no more percent signs, so we just output
+	// whatever is left.
 	if (ptr[0]) bc_file_puts(f, bc_flush_none, ptr);
 }
 
@@ -230,14 +286,19 @@ void bc_file_puts(BcFile *restrict f, BcFlushType type, const char *str) {
 }
 
 void bc_file_putchar(BcFile *restrict f, BcFlushType type, uchar c) {
+
 	if (f->len == f->cap) bc_file_flush(f, type);
+
 	assert(f->len < f->cap);
+
 	f->buf[f->len] = (char) c;
 	f->len += 1;
 }
 
 void bc_file_init(BcFile *f, int fd, char *buf, size_t cap) {
+
 	BC_SIG_ASSERT_LOCKED;
+
 	f->fd = fd;
 	f->buf = buf;
 	f->len = 0;