From ffd2550364d520e4ceb7957e25f7fb8c3ca68b97 Mon Sep 17 00:00:00 2001
From: Peter Evans <pevans@activecampaign.com>
Date: Wed, 6 Dec 2017 16:43:30 -0600
Subject: [PATCH] Better documentation; log to stdout

---
 include/log.h |  2 +-
 src/log.c     | 29 ++++++++++++++++++++++++++++-
 src/main.c    | 19 +++++++++++++++++--
 3 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/include/log.h b/include/log.h
index 87f90e7..a056a4c 100644
--- a/include/log.h
+++ b/include/log.h
@@ -5,7 +5,7 @@
 
 extern void log_write(int, const char *, ...);
 extern void log_close();
-extern void log_open();
+extern void log_open(FILE *);
 
 #define log_critical(...) log_write(0, __VA_ARGS__)
 #define log_error(...) log_write(0, __VA_ARGS__)
diff --git a/src/log.c b/src/log.c
index b0a5bbe..14e5941 100644
--- a/src/log.c
+++ b/src/log.c
@@ -4,11 +4,28 @@
 
 #include "log.h"
 
+/*
+ * This is the file stream we will write to for our logging. It can be
+ * any number of things, from a literal file on the filesystem, to
+ * stdout.
+ */
 static FILE *log_stream = NULL;
 
+/*
+ * This function will assign the log_stream variable to either a given
+ * file stream, or if none given, to the default location (which is a
+ * filename defined by the `LOG_FILENAME` macro).
+ */
 void
-log_open()
+log_open(FILE *stream)
 {
+    // Oh, you're telling _me_ what the stream is? Neat!
+    if (stream != NULL) {
+        log_stream = stream;
+        return;
+    }
+
+    // Oh, well. I'll just open this dang thing.
     log_stream = fopen(LOG_FILENAME, "w");
     if (log_stream == NULL) {
         perror("Couldn't open log file (" LOG_FILENAME ")");
@@ -16,6 +33,11 @@ log_open()
     }
 }
 
+/*
+ * Close the file stream we opened (or were given) in `log_open()`.
+ * Nota bene: if you passed stdout into log_open(), this will actually
+ * _close_ the stdout stream (!).
+ */
 void
 log_close()
 {
@@ -24,6 +46,11 @@ log_close()
     }
 }
 
+/*
+ * Write to the log stream. This function can accept variable arguments,
+ * ala `printf()`. There is some support for different log levels, but
+ * as you may note, we do not use them at present.
+ */
 void
 log_write(int level, const char *fmt, ...)
 {
diff --git a/src/main.c b/src/main.c
index 74b2339..e83096c 100644
--- a/src/main.c
+++ b/src/main.c
@@ -3,25 +3,40 @@
 
 #include "log.h"
 
+/*
+ * This function will establish the base environment that we want to use
+ * while we execute.
+ */
 static void
 init()
 {
-    log_open();
+    // We're literally using stdout in this heavy phase of development.
+    log_open(stdout);
 }
 
+/*
+ * And this is the teardown function.
+ */
 static void
 finish()
 {
     log_close();
 }
 
+/*
+ * This is what will run when the program begins, if you were new to how
+ * C works.
+ */
 int
 main(int argc, char **argv)
 {
     init();
 
-    // When we exit, we want to wrap up a few loose ends.
+    // When we exit, we want to wrap up a few loose ends. This syscall
+    // will ensure that `finish()` runs whether we return from main
+    // successfully or if we run `exit()` from elsewhere in the program.
     atexit(finish);
 
+    // ha ha ha ha #nervous #laughter
 	printf("Hello, world\n");
 }