From 76191991c8f0c7dc4bb77bc1e04c80d8070078d5 Mon Sep 17 00:00:00 2001
From: Peter Evans <pevans@activecampaign.com>
Date: Wed, 27 Dec 2017 01:14:52 -0600
Subject: [PATCH] Add a lot of missing documentation

---
 src/vm_screen.c | 47 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/src/vm_screen.c b/src/vm_screen.c
index 5495d3d..b5515eb 100644
--- a/src/vm_screen.c
+++ b/src/vm_screen.c
@@ -12,6 +12,13 @@
 #include "log.h"
 #include "vm_screen.h"
 
+/*
+ * Initialize the video of the vm_screen abstraction. This ends up being
+ * something that depends on our third-party graphics library; in other
+ * words, what do we need to do before we can even create a drawing
+ * surface to work with? If we are unable to properly do so, we return
+ * with an error.
+ */
 int
 vm_screen_init()
 {
@@ -23,6 +30,10 @@ vm_screen_init()
     return OK;
 }
 
+/*
+ * Something to do in the teardown phase of the program, undoing
+ * whatever we might have set up in the init function.
+ */
 void
 vm_screen_finish()
 {
@@ -30,7 +41,9 @@ vm_screen_finish()
 }
 
 /*
- * Return a new screen. We also set the color to black.
+ * Return a new screen. This ends up blanking out whatever we have here;
+ * we also do _not_ create any drawing surface, which is done separately
+ * with the add_window function.
  */
 vm_screen *
 vm_screen_create()
@@ -56,6 +69,14 @@ vm_screen_create()
     return screen;
 }
 
+/*
+ * The logical coordinates of a screen is a grid dimension separate from
+ * what the literal window size of our drawing surface. For instance, a
+ * machine may assume it has 320x240 pixels, but we are drawing on a
+ * surface that is twice the size, 640x480. In effect we aim to decouple
+ * the presumed drawing size from the actual drawing size, so the
+ * machine we emulate does not need to think about it.
+ */
 void
 vm_screen_set_logical_coords(vm_screen *screen, int xcoords, int ycoords)
 {
@@ -71,9 +92,16 @@ vm_screen_set_logical_coords(vm_screen *screen, int xcoords, int ycoords)
     }
 }
 
+/*
+ * This function will add a physical windowed, drawing surface to the
+ * screen object. This ends up being done through the third-party
+ * graphics library.
+ */
 int
 vm_screen_add_window(vm_screen *screen, int width, int height)
 {
+    // If HEADLESS is defined, we will assume we _don't_ want an actual
+    // drawing surface, but want to pretend we've added one. 
 #ifndef HEADLESS
     SDL_CreateWindowAndRenderer(
         width, height, 0, &screen->window, &screen->render);
@@ -100,12 +128,21 @@ vm_screen_add_window(vm_screen *screen, int width, int height)
     return OK;
 }
 
+/*
+ * Return the limit of the x coordinates our logical size can support.
+ * (This is not the literal width of the window, but rather the width of
+ * the drawing surface the machine will want to work with.)
+ */
 int
 vm_screen_xcoords(vm_screen *screen)
 {
     return screen->xcoords;
 }
 
+/*
+ * Like the xcoords function in every way and meaning; except here we
+ * return the y coordinate limit.
+ */
 int
 vm_screen_ycoords(vm_screen *screen)
 {
@@ -123,6 +160,10 @@ vm_screen_free(vm_screen *screen)
     free(screen);
 }
 
+/*
+ * Is the screen active? This function will be used by machines to
+ * determine if there's still a need to continue their run loops.
+ */
 bool
 vm_screen_active(vm_screen *screen)
 {
@@ -135,6 +176,10 @@ vm_screen_active(vm_screen *screen)
     return false;
 }
 
+/*
+ * Do whatever is required to refresh the screen with the changes we've
+ * made recently.
+ */
 void
 vm_screen_refresh(vm_screen *screen)
 {