From cf49374f1ab3dbde512321fc8b9f9e00e9e716b40a1dc5eaf0dd18818f14d5b5 Mon Sep 17 00:00:00 2001
From: Sergey Matveev <stargrave@stargrave.org>
Date: Tue, 15 Apr 2025 11:09:59 +0300
Subject: [PATCH] Some tiny comments about arguments

---
 tcl/keks.tcl | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/tcl/keks.tcl b/tcl/keks.tcl
index 64600ef..5089f06 100755
--- a/tcl/keks.tcl
+++ b/tcl/keks.tcl
@@ -28,7 +28,7 @@ proc char {v} {
     add [binary format c $v]
 }
 
-# Just add a raw value.
+# v is a complete raw value of the atom.
 proc RAW {v} {
     upvar buf buf
     add $v
@@ -54,6 +54,7 @@ proc TRUE {} {
     char [expr 0x03]
 }
 
+# v is either 16-bytes string, or UUID or uncompressed IP address.
 proc HEXLET {v} {
     set v [binary decode hex [string map {- "" : ""} $v]]
     if {[string length $v] != 16} {
@@ -146,6 +147,7 @@ proc STR {v} {
     _str [expr {0x80 | 0x40}] [encoding convertto utf-8 $v]
 }
 
+# v is a list of values that will be eval-ed.
 proc LIST {v} {
     upvar buf buf
     char [expr 0x08]
@@ -155,6 +157,7 @@ proc LIST {v} {
     EOC
 }
 
+# a and b are strings that are length-first compared.
 proc LenFirstSort {a b} {
     set a [encoding convertto utf-8 $a]
     set b [encoding convertto utf-8 $b]
@@ -179,6 +182,8 @@ proc LenFirstSort {a b} {
     error "non-unique keys"
 }
 
+# pairs is a list of key-value values. key is an ordinary string.
+# value will be eval-ed.
 proc MAP {pairs} {
     set d [dict create]
     set keys {}
@@ -196,6 +201,7 @@ proc MAP {pairs} {
     EOC
 }
 
+# v is a list of strings. It will become a map with NIL values.
 proc SET {v} {
     set args {}
     foreach k $v {
@@ -283,6 +289,7 @@ proc ToTAI {v} {
     return $v
 }
 
+# v is TAI number of seconds.
 proc TAI64 {v {n 0} {a 0}} {
     upvar buf buf
     set v [expr {$v + (1<<62)}]
-- 
2.48.1