Document convert_line() and gmi_to_html()

1 files changed, 11 insertions, 0 deletions

diff --git a/src/gemini2html.c b/src/gemini2html.c
index 0f6c2a0..e9f38f9 100644
--- a/src/gemini2html.c
+++ b/src/gemini2html.c
@@ -136,6 +136,7 @@ char* escape_text_add_tags(const char* opening_tag, const char* unescaped, const
     return escaped_with_tags;
 }
 
+/* Having more specific linetypes than the official Gemini spec turns out to be useful. */
 enum linetype{Text, Pre, Pre_toggle, Link, H1, H2, H3, Ul, Quote};
 
 /* Returns the line type.
@@ -302,6 +303,7 @@ char* convert_quote_line(const char* line, const size_t size) {
     return escape_text_add_tags("", line + pos, "", size - pos);
 }
 
+/* Generic function for other convert_line functions. */
 char* convert_line(const char* line, const size_t size, const enum linetype type) {
     switch (type) {
         case Text:       return convert_text_line(line, size);
@@ -316,6 +318,11 @@ char* convert_line(const char* line, const size_t size, const enum linetype type
     }
 }
 
+/* Reads in Gemini from standard in, outputs HTML to standard out.
+ * 
+ * Returns 0 if file conversion is successful, -1 if file reading/writing fails.
+ * Reads standard in line by line, converting each line to HTML and adding tags as necessary.
+ */
 int gmi_to_html(FILE* fp_gmi, FILE* fp_html) {
     if (fp_gmi == NULL || fp_html == NULL) return -1;
 
@@ -325,8 +332,10 @@ int gmi_to_html(FILE* fp_gmi, FILE* fp_html) {
     size_t len = 0;
     ssize_t read;
 
+    /* cur and prev help determine when to add HTML tags */
     enum linetype cur = Text;
     enum linetype prev = Text;
+
     bool pre_is_toggled = false;
 
     while ((read = getline(&line, &len, fp_gmi)) != -1) {
@@ -339,6 +348,7 @@ int gmi_to_html(FILE* fp_gmi, FILE* fp_html) {
             if (pre_is_toggled) fputs("<pre>\n", fp_html);
             else fputs("</pre>\n", fp_html);
         } else {
+            /* closing tags must be written before opening tags */
             if(cur != Ul && prev == Ul) fputs("</ul>\n", fp_html);
             else if (cur != Quote && prev == Quote) fputs("</blockquote>\n", fp_html);
 
@@ -358,6 +368,7 @@ int gmi_to_html(FILE* fp_gmi, FILE* fp_html) {
     free(line);
     line = NULL;
 
+    /* if a Pre, Ul, or Quote line is the last line, the getline loop won't automatically close its tag */
     switch (cur) {
         case Pre: fputs("</pre>\n", fp_html);          break;
         case Ul:  fputs("</ul>\n", fp_html);           break;