From 497f297877d2cf418b4ce32d5a97d9b1c50c26c7 Mon Sep 17 00:00:00 2001
From: d6 <d_m@plastic-idolatry.com>
Date: Tue, 28 Dec 2021 21:16:21 -0500
Subject: [PATCH] clean up comments

---
 math32.tal      | 52 +++++++++++++++++++++++++++++++++++++++++++++----
 test-math32.tal |  4 ++--
 2 files changed, 50 insertions(+), 6 deletions(-)

diff --git a/math32.tal b/math32.tal
index 0ad09c3..656e3ad 100644
--- a/math32.tal
+++ b/math32.tal
@@ -1,14 +1,58 @@
 ( math32.tal )
 ( )
-( This library supports arithmetic on 32-bit unsigned integers. )
-( 32-bit integers are represented by two 16-bit integers )
-( x** means xhi* xlo* )
+( This library supports arithmetic on 32-bit unsigned integers, )
+( also known as long values. )
+( )
+( 32-bit long values are represented by two 16-bit short values: )
+( )
+(      decimal  hexadecimal  uxn literals )
+(            0   0x00000000   #0000 #0000 )
+(            1   0x00000001   #0000 #0001 )
+(         4660   0x00001234   #0000 #1234 )
+(        65535   0x0000ffff   #0000 #ffff )
+(        65536   0x00010000   #0001 #0000 )
+(     16777215   0x00ffffff   #00ff #ffff )
+(   4294967295   0xffffffff   #ffff #ffff )
+( )
+( The most significant 16-bit, the "high bits", are stored first. )
+( We document long values as x** -- equivalent to xhi* xlo*. )
+( )
+( Operations supported: )
+( )
+(   - add32         x** y** -> z**    [x + y]  )
+(   - sub32         x** y** -> z**    [x - y]  )
+(   - mul16         x*  y*  -> z**    [x * y]  )
+(   - mul32         x** y** -> z**    [x * y]  )
+(   - div32         x** y** -> z**    [x / y]  )
+(   - negate32      x**     -> z**    [-x]     )
+(   - left-shift    x** n^  -> z**    [x<<n]   )
+(   - right-shift   x** n^  -> z**    [x>>n]   )
+(   - and32         x** y** -> z**    [x & y]  )
+(   - or32          x** y** -> z**    [x | y]  )
+(   - xor32         x** y** -> z**    [x ^ y]  )
+(   - complement32  x**     -> z**    [~x]     )
+(   - eq32          x** y** -> bool^  [x == y] )
+(   - ne32          x** y** -> bool^  [x != y] )
+(   - is-zero32     x**     -> bool^  [x == 0] )
+(   - non-zero32    x**     -> bool^  [x != 0] )
+(   - lt32          x** y** -> bool^  [x < y]  )
+(   - gt32          x** y** -> bool^  [x > y]  )
+(   - lteq32        x** y** -> bool^  [x <= y] )
+(   - gteq32        x** y** -> bool^  [x >= y] )
+(   - bitcount      x**     -> bool^  log2+1   )
+( )
+( In addition to the code this file uses 44 bytes of registers )
+( to store temporary state: )
+( )
+(   - shared memory, 16 bytes )
+(   - mul32 memory, 12 bytes )
+(   - div32 memory, 16 bytes )
 
 %DEBUG { #ff #0e DEO }
 %RTN  { JMP2r }
 %TOR { ROT ROT } ( a b c -> c a b )
 %TOR2 { ROT2 ROT2 }
-%COMPLEMENT32 { SWP2 #ffff EOR2 SWP2 #ffff EOR2 } )
+%COMPLEMENT32 { SWP2 #ffff EOR2 SWP2 #ffff EOR2 }
 
 ( bitcount: number of bits needed to represent number )
 ( equivalent to floor[log2[x]] + 1 )
diff --git a/test-math32.tal b/test-math32.tal
index c876981..c1ac0f2 100644
--- a/test-math32.tal
+++ b/test-math32.tal
@@ -2,7 +2,7 @@
 ( )
 ( methods for testing math32 and emitting output )
 
-%EMIT { #18 DEO } )
+%EMIT { #18 DEO }
 %DIGIT { #00 SWP ;digits ADD2 LDA EMIT }
 %SPACE { #20 EMIT }
 %NEWLINE { #0a EMIT }
@@ -28,7 +28,7 @@
     #57 ,&lo JMP &lo-digit #30
     &lo SUB SWP
 
-    ( higher char ))
+    ( higher char )
     DUP #3a LTH ,&hi-digit JCN
     #57 ,&hi JMP &hi-digit #30
     &hi SUB #40 SFT ORA