From f9e9f91663399ad3cf9322e0891246764b63c242 Mon Sep 17 00:00:00 2001
From: Jon Michael Aanes <jonjmaa@gmail.com>
Date: Tue, 18 Jul 2017 13:38:05 +0200
Subject: [PATCH] Minor documentation

---
 pretty.lua | 35 +++++++++++++++++++++++------------
 1 file changed, 23 insertions(+), 12 deletions(-)

diff --git a/pretty.lua b/pretty.lua
index 2e21eba..d585645 100644
--- a/pretty.lua
+++ b/pretty.lua
@@ -89,14 +89,25 @@ local function padnum(d)
 end
 
 local function alphanum_compare_strings (a, b)
-    local a_padded  =  tostring(a):gsub("%.?%d+", padnum)..("\0%3d"):format(#b)
-    local b_padded  =  tostring(b):gsub("%.?%d+", padnum)..("\0%3d"):format(#a)
+    -- Compares two strings alphanumerically.
+
+    assert(type(a) == 'string')
+    assert(type(b) == 'string')
+
+    local a_padded  =  a:gsub("%.?%d+", padnum)..("\0%3d"):format(#b)
+    local b_padded  =  b:gsub("%.?%d+", padnum)..("\0%3d"):format(#a)
     local A_padded, B_padded  =  a_padded:upper(), b_padded:upper()
     if A_padded == B_padded then  return  a_padded < b_padded  end
     return A_padded < B_padded
 end
 
-local function compare_key_value_pairs (a, b)
+local function compare_key_value_pair (a, b)
+    -- Function for comparing two key-value pairs, given as `{ key, value }`.
+    -- Pretty complex due to our high standards for sorting.
+
+    assert(type(a) == 'table')
+    assert(type(b) == 'table')
+
     -- Get types
     local type_key_a,   type_key_b   = type(a[1]), type(b[1])
     local type_value_a, type_value_b = type(a[2]), type(b[2])
@@ -134,7 +145,7 @@ local function get_key_value_pairs_in_proper_order (t)
         key_value_pairs[#key_value_pairs+1] = { key, value }
     end
 
-    table.sort(key_value_pairs, compare_key_value_pairs)
+    table.sort(key_value_pairs, compare_key_value_pair)
 
     return key_value_pairs
 end
@@ -151,11 +162,11 @@ local function fill_holes_in_key_value_pairs (key_value_pairs)
             key_value_pairs[#key_value_pairs+1] = { j, nil }
         end
     end
-    table.sort(key_value_pairs, compare_key_value_pairs)
+    table.sort(key_value_pairs, compare_key_value_pair)
 end
 
 local function smallest_secure_longform_string_level (str)
-    -- Determines the level a longform string needs to use, to avoid "code"
+    -- Determines the level a longform string needs to use, to avoid code
     -- injection. For example, if we want to use longform on the string
     -- 'Hello ]] World', we cannot use level-0 as this would result in
     -- '[[Hello ]] World]]', which could be an issue in certain applications.
@@ -176,9 +187,7 @@ local function escape_string (str)
 
     -- Do stuff
     local l = {}
-    for i = 1, #str do
-        l[#l+1] = CHAR_TO_STR_REPR[str:byte(i)]
-    end
+    for i = 1, #str do  l[#l+1] = CHAR_TO_STR_REPR[str:byte(i)]  end
     return table.concat(l, '')
 end
 
@@ -357,9 +366,6 @@ local function format_table (t, depth, l)
     if l[#l][1] == 'seperator' then  l[#l] = nil  end
     l[#l+1] = {'unindent', '}'}
 
-    --require 'fun' ()   -- DEBUG!
-    --DEBUG = map(operator.identity, l) -- DEBUG!
-
     -- Decide for short or long table formatting.
     local table_width  =  width_of_strings_in_l(l, start_of_table_i)
     if table_width <= MAX_WIDTH_FOR_SINGLE_LINE_TABLE then
@@ -377,6 +383,7 @@ end
 local function format_string (str, depth, l)
     -- TODO: Add option for escaping unicode characters.
     -- TODO: Improve cutstring argument.
+    -- TODO: Move this to it's own file.
 
     -- Error checking
     assert( type(str) == 'string' )
@@ -422,9 +429,13 @@ local function format_string (str, depth, l)
 end
 
 local function format_coroutine (value, depth, l)
+    -- Formats a coroutine. Unfortunantly we cannot gather a lot of information
+    -- about coroutines.
+
     -- Error check
     assert(type(value) == 'thread')
     assert(type(depth) == 'number' and type(l) == 'table')
+
     -- Do stuff
     l[#l+1] = coroutine.status(value)
     l[#l+1] = ' coroutine: '