general update

stdlib/arr.sl

@@ -44,7 +44,8 @@ word arr_free
     dup arr_cap 8 * 24 + free
 end
 
-# Helper: copy n qwords from src to dst [*, dst, src | n] -> [*]
+# Helper: copy n qwords from src to dst
+#arr_copy_elements [*, dst, src | n] -> [*]
 word arr_copy_elements
     while dup 0 > do
         over @ 3 pick swap !   # dst = *src

stdlib/debug.sl

@@ -1,13 +1,11 @@
 import stdlib.sl
 import io.sl
 
-#dump [* | n] -> [*]
-
 # dump takes the firts element from the stack
 # and prints that much consequent elements
 # from the stack while not modifying it
-# all variations have the same stack effect
 
+#dump [* | n] -> [*]
 word dump
 	1 swap
 	for
@@ -18,6 +16,7 @@ word dump
 	drop
 end
 
+#rdump [* | n] -> [*]
 # dump return stack
 word rdump
 	1 swap
@@ -29,6 +28,8 @@ word rdump
 	drop
 end
 
+#fdump [* | n] -> [*]
+#dump the stack with additional formatting
 word fdump
 	"[*, " write_buf
 	1 swap 1 +
@@ -44,6 +45,8 @@ word fdump
 	"]\n" write_buf
 end
 
+#frdump [* | n] -> [*]
+#dump the return stack with additional formatting
 word frdump
 	"[*, " write_buf
 	1 swap 1 -

stdlib/float.sl

@@ -1,6 +1,7 @@
 # L2 Floating Point Library (Double Precision)
 
 # Arithmetic
+#f+ [*, x1 | x2] -> [* | x3]
 :asm f+ {
     movq xmm0, [r12]
     add r12, 8
@@ -9,6 +10,7 @@
     movq [r12], xmm1
 } ;
 
+#f- [*, x1 | x2] -> [* | x3]
 :asm f- {
     movq xmm0, [r12]
     add r12, 8
@@ -17,6 +19,7 @@
     movq [r12], xmm1
 } ;
 
+#f* [*, x1 | x2] -> [* | x3]
 :asm f* {
     movq xmm0, [r12]
     add r12, 8
@@ -25,6 +28,7 @@
     movq [r12], xmm1
 } ;
 
+#f/ [*, x1 | x2] -> [* | x3]
 :asm f/ {
     movq xmm0, [r12]
     add r12, 8
@@ -33,6 +37,7 @@
     movq [r12], xmm1
 } ;
 
+#fneg [* | x] -> [* | -x]
 :asm fneg {
     movq xmm0, [r12]
     mov rax, 0x8000000000000000
@@ -42,6 +47,7 @@
 } ;
 
 # Comparison
+#f== [*, x1 | x2] -> [* | flag]
 :asm f== {
     movq xmm0, [r12]
     add r12, 8
@@ -52,6 +58,7 @@
     mov [r12], rax
 } ;
 
+#f< [*, x1 | x2] -> [* | flag]
 :asm f< {
     movq xmm0, [r12]      ; a
     add r12, 8
@@ -62,6 +69,7 @@
     mov [r12], rax
 } ;
 
+#f> [*, x1 | x2] -> [* | flag]
 :asm f> {
     movq xmm0, [r12]      ; a
     add r12, 8
@@ -73,25 +81,30 @@
 } ;
 
 # Conversion
+#int>float [* | x] -> [* | xf]
 :asm int>float {
     cvtsi2sd xmm0, [r12]
     movq [r12], xmm0
 } ;
 
+#float>int [* | xf] -> [* | x]
 :asm float>int {
     cvttsd2si rax, [r12]
     mov [r12], rax
 } ;
 
 # Output
+# extern declarations are required for runtime linking
 extern int printf(char* fmt, double x)
 extern int fflush(void* stream)
 
+#fput [* | xf] -> [*]
 word fput
     "%f" drop swap printf drop
     0 fflush drop
 end
 
+#fputln [* | xf] -> [*]
 word fputln
     "%f\n" drop swap printf drop
     0 fflush drop

stdlib/io.sl

@@ -1,9 +1,8 @@
 # L2 IO Primitives
 
+#Reads the file at the given path (pointer+length, not null-terminated),
+#returns (addr len) of mapped file, or (tag neg_errno) on error.
 #read_file [*, path_addr | path_len] -> [*, addr | len] || [*, tag | neg_errno]
-#   Reads the file at the given path (pointer+length, not null-terminated),
-#   returns (addr len) of mapped file, or (tag neg_errno) on error.
-
 :asm read_file {
 	; stack: path_addr (NOS), path_len (TOS)
 	mov rdx, [r12]        ; path_len
@@ -191,6 +190,7 @@
 }
 ;
 
+#print [* | x] -> [*]
 :asm print (effects string-io) {
 	mov rax, [r12]      ; len or int value
 	mov rbx, [r12 + 8]  ; possible address
@@ -353,8 +353,11 @@
 }
 ;
 
+#cr [*] -> [*]
 inline word cr 10 putc end
 
+#puts [* | x] -> [*]
 inline word puts write_buf cr end
 
-inline   word eputs ewrite_buf cr end
+#eputs [* | x] -> [*]
+inline word eputs ewrite_buf cr end

stdlib/utils.sl

@@ -213,12 +213,11 @@ end
 #  Multi-substitution format words
 # ---------------------------------------------------------------------------
 
-#formats [*, sN_addr, sN_len, ..., s1_addr, s1_len, fmt_addr | fmt_len]
-#     -> [*, result_addr | result_len]
 # Replaces each '%' in fmt with the corresponding string argument.
 # s1 (just below fmt) maps to the first '%', s2 to the second, etc.
 # The number of string-pair args must equal the number of '%' markers.
 # Returns a newly allocated string, or fmt as-is when there are no '%'.
+#formats [*, sN_addr, sN_len, ..., s1_addr, s1_len, fmt_addr | fmt_len] -> [*, result_addr | result_len]
 word formats
     2dup 37 count_char_in_str nip nip  # count '%' -> n
     dup 0 == if
@@ -236,12 +235,12 @@ word formats
     end
 end
 
-#formati [*, iN, ..., i1, fmt_addr | fmt_len]
-#     -> [*, result_addr | result_len]
+
 # Replaces each '%' in fmt with the decimal string of the corresponding
 # integer argument.  i1 (just below fmt) maps to the first '%', etc.
 # The number of int args must equal the number of '%' markers.
 # Returns a newly allocated string, or fmt as-is when there are no '%'.
+#formati [*, iN, ..., i1, fmt_addr | fmt_len] -> [*, result_addr | result_len]
 word formati
     2dup 37 count_char_in_str nip nip  # count '%' -> n
     dup 0 == if