From 6e89d6e2633e7cf88535ab33f4e02275fe97d071 Mon Sep 17 00:00:00 2001
From: Nathan Fisher <nfisher.sr@gmail.com>
Date: Sat, 4 Nov 2023 00:32:53 -0400
Subject: [PATCH] Better docs and code commenting

---
 gemtext-parser.c         |  3 +++
 include/gemtext-parser.h | 19 ++++++++++---------
 2 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/gemtext-parser.c b/gemtext-parser.c
index cc5518d..7e0fa3f 100644
--- a/gemtext-parser.c
+++ b/gemtext-parser.c
@@ -624,6 +624,8 @@ int parseGemtext(gemtextParser *parser, gemtextNodeQueue *nq) {
                 return ret;
             }
         } else {
+            // If we were unable to read a char, assume we're at the end of the
+            // stream and send the node to the queue
             if (parser->state != lineStart && parser->state != trimStart) {
                 switch (parser->nodeType) {
                 case preformattedNode:
@@ -638,6 +640,7 @@ int parseGemtext(gemtextParser *parser, gemtextNodeQueue *nq) {
                 }
                 if (ret) return ret;
             }
+            // Send an `endOfStream` node since we know we're done
             node = calloc(1, sizeof(gemtextNode));
             if (node == NULL) return errno;
             node->nodeType = endOfStream;
diff --git a/include/gemtext-parser.h b/include/gemtext-parser.h
index 48f99cf..3cc058d 100644
--- a/include/gemtext-parser.h
+++ b/include/gemtext-parser.h
@@ -89,6 +89,7 @@ typedef struct {
     };
 } gemtextParser;
 
+/** A Gemtext node */
 struct _gemtextNode {
     struct _gemtextNode  *next;     ///< The next line in the queue
     struct _gemtextNode  *prev;     ///< The previous line in the queue
@@ -163,30 +164,30 @@ void gemtextParserDestroy(gemtextParser *parser);
 int gemtextNodeQueueInit(gemtextNodeQueue *nq);
 
 /**
- * Pushes a gemtextLine into the queue. This function will not fail, but
+ * Pushes a gemtextNode into the queue. This function will not fail, but
  * can block if another thread holds the gemtextQueue's internal mutex.
- * \param nq The queue which will receive the gemtext line
+ * \param nq The queue which will receive the gemtext node
  * \param node The gemtextNode to be queued
  */
 void gemtextNodeQueuePush(gemtextNodeQueue *nq, gemtextNode *node);
 
 /**
- * Gets the oldest line inserted in the queue. This function will either
- * return a valid gemtextLine or block until one becomes available.
- * \param nq The queue from which we are attempting to pop a line
+ * Gets the oldest node inserted in the queue. This function will either
+ * return a valid gemtextNode or block until one becomes available.
+ * \param nq The queue from which we are attempting to pop a node
  */
 gemtextNode* gemtextNodeQueuePop(gemtextNodeQueue *nq);
 
 /**
- * Attempts to get the oldest line inserted in the queue. If there are no lines
+ * Attempts to get the oldest node inserted in the queue. If there are no nodes
  * left in the queue, returns NULL.
- * \param nq The queue from which we are attempting to pop a line
+ * \param nq The queue from which we are attempting to pop a node
  */
 gemtextNode* gemtextNodeQueueTryPop(gemtextNodeQueue *nq);
 
 /**
- * Frees all memory associated with a gemtextLine structure
- * \param lq The gemtextLine to be de-allocated
+ * Frees all memory associated with a gemtextNode structure
+ * \param node The gemtextNode to be de-allocated
  */
 void gemtextNodeDeinit(gemtextNode *node);