Document the rest of the convert_*() functions

1 files changed, 65 insertions, 10 deletions

diff --git a/src/gemini2html.c b/src/gemini2html.c
index a212916..0f6c2a0 100644
--- a/src/gemini2html.c
+++ b/src/gemini2html.c
@@ -177,34 +177,45 @@ char* convert_pre_line(const char* line, const size_t size) {
 /* Converts the preformatting toggle line to HTML.
  * 
  * Returns the empty string. Preformatting toggle lines aren't meant to be displayed.
+ * convert_pre_toggle_line() doesn't know if the starting or ending toggle line, so gmi_to_html() handles the pre tags.
  */
 char* convert_pre_toggle_line(const char* line, const size_t size) {
     return strdup("");
 }
 
+/* Converts the link text line to HTML.
+ * 
+ * Returns the escaped href and link text surrounded by a tags, appending a newline if there isn't one.
+ * The heading prefix "=>" and any immediately following whitespace (spaces and tabs) is omitted.
+ * If no link text is provided, the href is used as the link text.
+ * 
+ * Examples:
+ * convert_link_line("=>   https://google.com Goolag ") => "<a rel=\"noreferrer noopener\" href=\"https://google.com\"">Goolag </a>\n"
+ * convert_link_line("=>   https://google.com") => "<a rel=\"noreferrer noopener\" href=\"https://google.com\"">https://google.com</a>\n"
+ */
 char* convert_link_line(const char* line, const size_t size) {
-    /* skip whitespace before link */
-    size_t before_link = 2;
-    skip_whitespace(line, &before_link);
+    /* skip whitespace before href */
+    size_t before_href = 2;
+    skip_whitespace(line, &before_href);
 
-    /* find end of link */
-    size_t after_link = before_link;
-    skip_non_whitespace(line, &after_link);
+    /* find end of href */
+    size_t after_href = before_href;
+    skip_non_whitespace(line, &after_href);
 
     /* find beginning of link text */
-    size_t before_link_text = after_link;
+    size_t before_link_text = after_href;
     skip_whitespace(line, &before_link_text);
 
-    char* escaped_href = escape_text_add_tags("<a rel=\"noreferrer noopener\" href=\"", line + before_link, "\">", after_link - before_link);
+    char* escaped_href = escape_text_add_tags("<a rel=\"noreferrer noopener\" href=\"", line + before_href, "\">", after_href - before_href);
 
     /* escaped_href will be appended to, so remove newline */
     escaped_href[strlen(escaped_href) - 1] = '\0';
 
     char* escaped_with_tags = NULL;
 
-    /* if no link text exists, use the link as link text */
+    /* if no link text exists, use the href as link text */
     if (line[before_link_text] == '\0') {
-        escaped_with_tags = escape_text_add_tags(escaped_href, line + before_link, "</a>", after_link - before_link);
+        escaped_with_tags = escape_text_add_tags(escaped_href, line + before_href, "</a>", after_href - before_href);
     /* otherwise use the link text */
     } else {
         escaped_with_tags = escape_text_add_tags(escaped_href, line + before_link_text, "</a>", size - before_link_text);
@@ -217,30 +228,74 @@ char* convert_link_line(const char* line, const size_t size) {
     return escaped_with_tags;
 }
 
+/* Converts the heading text line to HTML.
+ * 
+ * Returns the escaped heading text surrounded by h1 tags, appending a newline if there isn't one.
+ * The heading prefix "#" and any immediately following whitespace (spaces and tabs) is omitted.
+ * 
+ * Example:
+ * convert_h1_line("#   i'm an h1 heading! ") => "<h1>i&apos;m an h1 heading! </h1>\n"
+ */
 char* convert_h1_line(const char* line, const size_t size) {
     size_t pos = 1;
     skip_whitespace(line, &pos);
     return escape_text_add_tags("<h1>", line + pos, "</h1>", size - pos);
 }
 
+/* Converts the heading text line to HTML.
+ * 
+ * Returns the escaped heading text surrounded by h2 tags, appending a newline if there isn't one.
+ * The heading prefix "##" and any immediately following whitespace (spaces and tabs) is omitted.
+ * 
+ * Example:
+ * convert_h2_line("##   i'm an h2 heading! ") => "<h2>i&apos;m an h2 heading! </h2>\n"
+ */
 char* convert_h2_line(const char* line, const size_t size) {
     size_t pos = 2;
     skip_whitespace(line, &pos);
     return escape_text_add_tags("<h2>", line + pos, "</h2>", size - pos);
 }
 
+/* Converts the heading text line to HTML.
+ * 
+ * Returns the escaped heading text surrounded by h3 tags, appending a newline if there isn't one.
+ * The heading prefix "###" and any immediately following whitespace (spaces and tabs) is omitted.
+ * 
+ * Example:
+ * convert_h3_line("###   i'm an h3 heading! ") => "<h3>i&apos;m an h3 heading! </h3>\n"
+ */
 char* convert_h3_line(const char* line, const size_t size) {
     size_t pos = 3;
     skip_whitespace(line, &pos);
     return escape_text_add_tags("<h3>", line + pos, "</h3>", size - pos);
 }
 
+/* Converts the unordered list line to HTML.
+ * 
+ * Returns the escaped list text surrounded by list tags, appending a newline if there isn't one.
+ * The list line prefix "*" and any immediately following whitespace (spaces and tabs) is omitted.
+ * 
+ * Example:
+ * convert_ul_line("*   i'm a list item! ") => "<li>i&apos;m a list item! </li>\n"
+ * 
+ * convert_ul_line() doesn't know when it's at the first or last list item, so gmi_to_html() handles the surrounding ul tags.
+ */
 char* convert_ul_line(const char* line, const size_t size) {
     size_t pos = 1;
     skip_whitespace(line, &pos);
     escape_text_add_tags("<li>", line + pos, "</li>", size - pos);
 }
 
+/* Converts the quote line to HTML.
+ * 
+ * Returns the escaped quote text, appending a newline if there isn't one.
+ * The quote line prefix ">" and any immediately following whitespace (spaces and tabs) is omitted.
+ * 
+ * Example:
+ * convert_quote_line(">   i'm a quote item! ") => "i&apos;m a quote item! \n"
+ * 
+ * convert_quote_line() doesn't know when it's at the first or last quote line, so gmi_to_html() handles the surrounding blockquote tags.
+ */
 char* convert_quote_line(const char* line, const size_t size) {
     size_t pos = 1;
     skip_whitespace(line, &pos);