refactor

7 files changed, 59 insertions, 40 deletions

diff --git a/TODO.md b/TODO.md
deleted file mode 100644
index b75b26a8..00000000
--- a/TODO.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# TODO
-
-Adjust code to reflect the google style guide. Use this to practice navigating the Vim quickfix list.
-
-* comment complex functions
-* comment all lib functions
-* buetow.org.conf: declare -xr FOO=bar both constant and env.
diff --git a/packages/assert.source.sh b/packages/assert.source.sh
index 551d1623..c3ad0a6a 100644
--- a/packages/assert.source.sh
+++ b/packages/assert.source.sh
@@ -1,3 +1,4 @@
+# Unit test for whether 2 given strings equal.
 assert::equals () {
     local -r result="$1"; shift
     local -r expected="$1"; shift
@@ -16,6 +17,7 @@ ERROR
     log VERBOSE "Result in $callee as expected: '$expected'"
 }
 
+# Unit test for whether a given string is not empty.
 assert::not_empty () {
     local -r name="$1"; shift
     local -r content="$1"; shift
diff --git a/packages/atomfeed.source.sh b/packages/atomfeed.source.sh
index feb074a8..3a3e1e73 100644
--- a/packages/atomfeed.source.sh
+++ b/packages/atomfeed.source.sh
@@ -1,3 +1,4 @@
+# Retrieves meta data of a given blog post. Generate new meta info if not yet exists.
 atomfeed::meta () {
     local -r gmi_file_path="$1"; shift
     local -r meta_file=$($SED 's|gemtext|meta|; s|.gmi$|.meta|;' <<< "$gmi_file_path")
@@ -36,6 +37,7 @@ META
     test $is_draft == yes && rm "$meta_file"
 }
 
+# Retrieves the core content as XHTML of the blog post, to include to the feed.
 atomfeed::content () {
     local -r gmi_file_path="$1"; shift
     log VERBOSE "Retrieving feed content from $gmi_file_path"
@@ -50,6 +52,7 @@ atomfeed::content () {
     "
 }
 
+# Generate an atom.xml feed file.
 atomfeed::generate () {
     local -r gemfeed_dir="$CONTENT_DIR/gemtext/gemfeed"
     local -r atom_file="$gemfeed_dir/atom.xml"
diff --git a/packages/generate.source.sh b/packages/generate.source.sh
index 0f07af56..67a9b7e5 100644
--- a/packages/generate.source.sh
+++ b/packages/generate.source.sh
@@ -1,3 +1,4 @@
+# Generates a HTML or Markdown link from given Gemtext link.
 generate::make_link () {
     local -r what="$1"; shift
     local -r line="${1/=> }"; shift
@@ -18,7 +19,7 @@ generate::make_link () {
         if [[ "$what" == md ]]; then
             md::make_img "$link" "$descr"
         else
-            html::make_img "$link" "$(html::special "$descr")"
+            html::make_img "$link" "$(html::encode "$descr")"
         fi
         return
     fi
@@ -26,11 +27,12 @@ generate::make_link () {
     if [[ "$what" == md ]]; then
         md::make_link "$link" "$descr"
     else
-        html::make_link "$link" "$(html::special "$descr")"
+        html::make_link "$link" "$(html::encode "$descr")"
     fi
 }
 
-generate::fromgmi_ () {
+# Internal helper function for generate::fromgmi
+generate::_fromgmi () {
     local -r src="$1"; shift
     local -r format="$1"; shift
     local dest=${src/gemtext/$format}
@@ -50,6 +52,7 @@ generate::fromgmi_ () {
     test "$ADD_GIT" == yes && git add "$dest"
 }
 
+# Adds other docs (e.g. images, videos) from Gemtext to output format.
 generate::fromgmi_add_docs () {
     local -r src="$1"; shift
     local -r format="$1"; shift
@@ -61,6 +64,17 @@ generate::fromgmi_add_docs () {
     test "$ADD_GIT" == yes && git add "$dest"
 }
 
+# Remove docs from output format which aren't present in Gemtext anymore.
+generate::fromgmi_cleanup_docs () {
+    local -r src="$1"; shift
+    local -r format="$1"; shift
+    local dest=${src/.$format/.gmi}
+    dest=${dest/$format/gemtext}
+
+    test ! -f "$dest" && test "$ADD_GIT" == yes && git rm "$src"
+}
+
+# Converts the Gemtext Atom feed to a HTML Atom feed.
 generate::convert_gmi_atom_to_html_atom () {
     local -r format="$1"; shift
     test "$format" != html && return
@@ -74,15 +88,7 @@ generate::convert_gmi_atom_to_html_atom () {
     test "$ADD_GIT" == yes && git add "$CONTENT_DIR/html/gemfeed/atom.xml"
 }
 
-generate::fromgmi_cleanup () {
-    local -r src="$1"; shift
-    local -r format="$1"; shift
-    local dest=${src/.$format/.gmi}
-    dest=${dest/$format/gemtext}
-
-    test ! -f "$dest" && test "$ADD_GIT" == yes && git rm "$src"
-}
-
+# Generate a given output format from a Gemtext file.
 generate::fromgmi () {
     local -i num_gmi_files=0
     local -i num_doc_files=0
@@ -92,7 +98,7 @@ generate::fromgmi () {
     while read -r src; do
         (( num_gmi_files++ ))
         for format in "$@"; do
-            generate::fromgmi_ "$src" "$format"
+            generate::_fromgmi "$src" "$format"
         done
     done < <(find "$CONTENT_DIR/gemtext" -type f -name \*.gmi)
 
@@ -118,7 +124,7 @@ generate::fromgmi () {
     # Remove obsolete files from ./html/
     for format in "$@"; do
         find "$CONTENT_DIR/$format" -type f | while read -r src; do
-            generate::fromgmi_cleanup "$src" "$format"
+            generate::fromgmi_cleanup_docs "$src" "$format"
         done
     done
 
diff --git a/packages/html.source.sh b/packages/html.source.sh
index d8d2fc66..d295c7a7 100644
--- a/packages/html.source.sh
+++ b/packages/html.source.sh
@@ -1,4 +1,5 @@
-html::special () {
+# Convert special characters to their HTML codes
+html::encode () {
     $SED '
         s|\&|\&amp;|g;
         s|<|\&lt;|g;
@@ -6,22 +7,26 @@ html::special () {
     ' <<< "$@"
 }
 
+# Make a HTML paragraph.
 html::make_paragraph () {
     local -r text="$1"; shift
-    test -n "$text" && echo "<p>$(html::special "$text")</p>"
+    test -n "$text" && echo "<p>$(html::encode "$text")</p>"
 }
 
+# Make a HTML header.
 html::make_heading () {
     local -r text=$($SED -E 's/^#+ //' <<< "$1"); shift
     local -r level="$1"; shift
-    echo "<h${level}>$(html::special "$text")</h${level}>"
+    echo "<h${level}>$(html::encode "$text")</h${level}>"
 }
 
+# Make a HTML quotation
 html::make_quote () {
     local -r quote="${1/> }"
-    echo "<p class=\"quote\"><i>$(html::special "$quote")</i></p>"
+    echo "<p class=\"quote\"><i>$(html::encode "$quote")</i></p>"
 }
 
+# Make a HTML image
 html::make_img () {
     local link="$1"; shift
     local descr="$1"; shift
@@ -36,6 +41,7 @@ html::make_img () {
     echo "<br />"
 }
 
+# Make a HTML hyperlink
 html::make_link () {
     local link="$1"; shift
     local descr="$1"; shift
@@ -45,6 +51,7 @@ html::make_link () {
     echo "<a class=\"textlink\" href=\"$link\">$descr</a><br />"
 }
 
+## Convert Gemtext to HTML
 html::fromgmi () {
     local is_list=no
     local is_plain=no
@@ -52,7 +59,7 @@ html::fromgmi () {
     while IFS='' read -r line; do
         if [[ "$is_list" == yes ]]; then
             if [[ "$line" == '* '* ]]; then
-                echo "<li>$(html::special "${line/\* /}")</li>"
+                echo "<li>$(html::encode "${line/\* /}")</li>"
             else
                 is_list=no
                 echo "</ul>"
@@ -64,7 +71,7 @@ html::fromgmi () {
                 echo "</pre>"
                 is_plain=no
             else
-                html::special "$line"
+                html::encode "$line"
             fi
             continue
         fi
@@ -101,6 +108,7 @@ html::fromgmi () {
     done
 }
 
+## Test HTML package.
 html::test () {
     local line='Hello world! This is a paragraph.'
     assert::equals "$(html::make_paragraph "$line")" '<p>Hello world! This is a paragraph.</p>'
diff --git a/packages/log.source.sh b/packages/log.source.sh
index 55d693ec..2c6e1b3f 100644
--- a/packages/log.source.sh
+++ b/packages/log.source.sh
@@ -1,3 +1,4 @@
+# Log a message.
 log () {
     local -r level="$1"; shift
 
@@ -6,10 +7,12 @@ log () {
     done | log::_pipe "$level"
 }
 
+# Log a stream through a pipe.
 log::pipe () {
     log::_pipe "$1"
 }
 
+# Internal log implementation.
 log::_pipe () {
     local -r level="$1"; shift
 
diff --git a/packages/md.source.sh b/packages/md.source.sh
index 197bdcf7..2f85b3c2 100644
--- a/packages/md.source.sh
+++ b/packages/md.source.sh
@@ -1,3 +1,4 @@
+# Make a Markdown image.
 md::make_img () {
     local link="$1"; shift
     local descr="$1"; shift
@@ -9,6 +10,7 @@ md::make_img () {
     fi
 }
 
+# Make a Markdown hyperlink.
 md::make_link () {
     local link="$1"; shift
     local descr="$1"; shift
@@ -19,6 +21,21 @@ md::make_link () {
     echo "[$descr]($link)  "
 }
 
+# Convert Gemtext to Markdown.
+md::fromgmi () {
+    while IFS='' read -r line; do
+        case "$line" in
+            '=> '*)
+                generate::make_link md "$line"
+                ;;
+            *)
+                echo "$line"
+                ;;
+        esac
+    done
+}
+
+# Test the Markdown package.
 md::test () {
     local line='=> https://example.org'
     assert::equals "$(generate::make_link md "$line")" \
@@ -40,16 +57,3 @@ md::test () {
     assert::equals "$(generate::make_link md "$line")" \
         '[![Image description](http://example.org/image.png "Image description")](http://example.org/image.png)  '
 }
-
-md::fromgmi () {
-    while IFS='' read -r line; do
-        case "$line" in
-            '=> '*)
-                generate::make_link md "$line"
-                ;;
-            *)
-                echo "$line"
-                ;;
-        esac
-    done
-}