From 5811ff4554da3d980ff32a83efa35ea1a4512484 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Tue, 12 Jan 2021 21:28:44 -0800
Subject: Adding comments

---
 compiler.c    |  3 +++
 file_loader.c | 21 +++++++++++++++++++++
 json.c        |  7 ++++++-
 printing.c    | 25 ++++++++++++++++++++++---
 vm.c          |  3 +++
 5 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/compiler.c b/compiler.c
index 74044a8..1c8974c 100644
--- a/compiler.c
+++ b/compiler.c
@@ -581,6 +581,9 @@ vm_op_t *bp_replacement(file_t *f, vm_op_t *pat, const char *replacement)
     return op;
 }
 
+//
+// Compile a string representing a BP pattern into an opcode object.
+//
 vm_op_t *bp_pattern(file_t *f, const char *str)
 {
     vm_op_t *op = bp_simplepattern(f, str);
diff --git a/file_loader.c b/file_loader.c
index 69b71ca..1452907 100644
--- a/file_loader.c
+++ b/file_loader.c
@@ -15,6 +15,10 @@
 #include "file_loader.h"
 #include "utils.h"
 
+//
+// In the file object, populate the `lines` array with pointers to the
+// beginning of each line.
+//
 static void populate_lines(file_t *f)
 {
     // Calculate line numbers:
@@ -107,6 +111,10 @@ void intern_file(file_t *f)
     populate_lines(f);
 }
 
+//
+// Free a file and all memory contained inside its members, then set the input
+// pointer to NULL.
+//
 void destroy_file(file_t **f)
 {
     if ((*f)->filename) {
@@ -128,6 +136,9 @@ void destroy_file(file_t **f)
     xfree(f);
 }
 
+//
+// Given a pointer, determine which line number it points to.
+//
 size_t get_line_number(file_t *f, const char *p)
 {
     // TODO: binary search
@@ -138,18 +149,28 @@ size_t get_line_number(file_t *f, const char *p)
     return f->nlines;
 }
 
+//
+// Given a pointer, determine which character offset within the line it points to.
+//
 size_t get_char_number(file_t *f, const char *p)
 {
     size_t linenum = get_line_number(f, p);
     return 1 + (size_t)(p - f->lines[linenum-1]);
 }
 
+//
+// Return a pointer to the line with the specified line number.
+//
 const char *get_line(file_t *f, size_t line_number)
 {
     if (line_number == 0 || line_number > f->nlines) return NULL;
     return f->lines[line_number - 1];
 }
 
+//
+// Print the filename/line number, followed by the given message, followed by
+// the line itself.
+//
 void fprint_line(FILE *dest, file_t *f, const char *start, const char *end, const char *fmt, ...)
 {
     if (start < f->contents) start = f->contents;
diff --git a/json.c b/json.c
index f7e34fe..22a3ae2 100644
--- a/json.c
+++ b/json.c
@@ -7,7 +7,9 @@
 #include "types.h"
 
 //
-// Print a match as JSON
+// Helper function for json_match().
+// `comma` is used to track whether a comma will need to be printed before the
+// next object or not.
 //
 static int _json_match(const char *text, match_t *m, int comma, int verbose)
 {
@@ -41,6 +43,9 @@ static int _json_match(const char *text, match_t *m, int comma, int verbose)
     return 1;
 }
 
+//
+// Print a match object as a JSON object.
+//
 void json_match(const char *text, match_t *m, int verbose)
 {
     _json_match(text, m, 0, verbose);
diff --git a/printing.c b/printing.c
index f35957f..71fff17 100644
--- a/printing.c
+++ b/printing.c
@@ -21,6 +21,10 @@ typedef struct {
     const char *color;
 } print_state_t;
 
+//
+// Return the height of a match object (i.e. the number of descendents of the
+// structure).
+//
 static int match_height(match_t *m)
 {
     int height = 0;
@@ -31,6 +35,9 @@ static int match_height(match_t *m)
     return 1 + height;
 }
 
+//
+// Print a visual explanation for the as-yet-unprinted matches provided.
+//
 static void _visualize_matches(match_node_t *firstmatch, int depth, const char *text, size_t textlen)
 {
     if (!firstmatch) return;
@@ -153,6 +160,10 @@ static void _visualize_matches(match_node_t *firstmatch, int depth, const char *
     }
 }
 
+//
+// Recursively look for references to a rule called "pattern" and print an
+// explanation for each one.
+//
 static void _visualize_patterns(match_t *m)
 {
     if (m->op->type == VM_REF && streq(m->op->args.s, "pattern")) {
@@ -165,15 +176,20 @@ static void _visualize_patterns(match_t *m)
     }
 }
 
+//
+// For a match object, print a visual explanation for each "pattern" matched
+// inside it.
+//
 void visualize_match(match_t *m)
 {
     printf("\033[?7l");
-    //match_node_t first = {.m = m};
-    //_visualize_matches(&first, 0, m->start, (m->end - m->start));
     _visualize_patterns(m);
     printf("\033[?7h");
 }
 
+//
+// Print a line number.
+//
 static void print_line_number(FILE *out, print_state_t *state, print_options_t options)
 {
     state->printed_line = state->line;
@@ -185,7 +201,7 @@ static void print_line_number(FILE *out, print_state_t *state, print_options_t o
 }
 
 //
-// Print a match with replacements and highlighting.
+// Helper function for print_match(), using a struct to keep track of some state.
 //
 static void _print_match(FILE *out, file_t *f, match_t *m, print_state_t *state, print_options_t options)
 {
@@ -275,6 +291,9 @@ static void _print_match(FILE *out, file_t *f, match_t *m, print_state_t *state,
     }
 }
 
+//
+// Print a match with replacements and highlighting.
+//
 void print_match(FILE *out, file_t *f, match_t *m, print_options_t options)
 {
     print_state_t state = {.line = 1, .color = "\033[0m"};
diff --git a/vm.c b/vm.c
index 91c29ae..7cfeda9 100644
--- a/vm.c
+++ b/vm.c
@@ -522,6 +522,9 @@ match_t *get_capture(match_t *m, const char **r)
     return NULL;
 }
 
+//
+// Wrapper function for _match() to kickstart the recursion info.
+//
 match_t *match(def_t *defs, file_t *f, const char *str, vm_op_t *op, unsigned int flags)
 {
     return _match(defs, f, str, op, flags, NULL);
-- 
cgit v1.2.3