Some tiny comments about arguments

diff --git a/tcl/keks.tcl b/tcl/keks.tcl
index 64600ef20dd9844bd7a1b5ca1ad600222d0f99f0f4e544f5a51ac9f6c2480a8c..5089f06cf3d17125ac6e93e78bb645c2fc31f112d72abfae01fb03816beae64e 100755 (executable)
--- 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)}]