diff --git a/functions/coalesce.fish b/functions/coalesce.fish
index 5ad924e..05db004 100644
--- a/functions/coalesce.fish
+++ b/functions/coalesce.fish
@@ -1,4 +1,5 @@
 function coalesce
+    # coalesce returns the first non-empty argument passed to it
     for x in $argv
         if test -n "$x"
             echo "$x"
diff --git a/functions/shorten_path.fish b/functions/shorten_path.fish
index 2ee4c71..e654b21 100644
--- a/functions/shorten_path.fish
+++ b/functions/shorten_path.fish
@@ -1,17 +1,31 @@
 function shorten_path
+    # shorten_path is a script to compress a path without sacrificing to much readibility
+    # It shortens each segment in a path to one character except the last
+    # e.g.:
+    # /path/to/somewhere        → /p/t/somewhere
+    # some/relative/path        → s/r/path
+    # singel_segment_path       → singel_segment_path
+    # /path/with//empty/space   → /p/w//e/space
+
+    # handle single segment paths (don't contain a slash)
     if ! string match -q -- '*/*' $argv[1]
         echo $argv[1]
         return
     end
 
+    # split
     set -l segments (string split '/' (string trim -r -c '/' $argv[1]))
     
-    if test -n $segments[1]
+    # handle relative paths
+    if test -n "$segments[1]"
         echo -n (string split '' $segments[1])[1]
     end
 
+    # print shortened segments
     for seg in $segments[2..-2]
         echo -n '/'(string split '' $seg)[1]
     end
+
+    # print final segment
     echo '/'$segments[-1]
 end
\ No newline at end of file