diff --git a/math32.tal b/math32.tal
index 656e3ad..fad17a1 100644
--- a/math32.tal
+++ b/math32.tal
@@ -19,27 +19,30 @@
 ( )
 ( 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   )
+(   NAME            STACK EFFECT        DEFINITION       )
+(   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               )
+(   lshift32        x** n^  -> z**      x<<n             )
+(   rshift32        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           )
+(   bitcount8       x^      -> bool^    floor(log2(x))+1 )
+(   bitcount16      x*      -> bool^    floor(log2(x))+1 )
+(   bitcount32      x**     -> bool^    floor(log2(x))+1 )
 ( )
 ( In addition to the code this file uses 44 bytes of registers )
 ( to store temporary state: )
@@ -51,7 +54,7 @@
 %DEBUG { #ff #0e DEO }
 %RTN  { JMP2r }
 %TOR { ROT ROT } ( a b c -> c a b )
-%TOR2 { ROT2 ROT2 }
+( %TOR2 { ROT2 ROT2 } )
 %COMPLEMENT32 { SWP2 #ffff EOR2 SWP2 #ffff EOR2 }
 
 ( bitcount: number of bits needed to represent number )
@@ -172,15 +175,15 @@
 ( bit shifting )
 
 ( x >> n )
-@right-shift ( x** n^ -> x<<n )
-    DUP #08 LTH ;right-shift0 JCN2 ( x n )
-    DUP #10 LTH ;right-shift1 JCN2 ( x n )
-    DUP #18 LTH ;right-shift2 JCN2 ( x n )
-    ;right-shift3 JMP2 ( x n )    
+@rshift32 ( x** n^ -> x<<n )
+    DUP #08 LTH ;rshift32-0 JCN2 ( x n )
+    DUP #10 LTH ;rshift32-1 JCN2 ( x n )
+    DUP #18 LTH ;rshift32-2 JCN2 ( x n )
+    ;rshift32-3 JMP2 ( x n )
     RTN
 
 ( shift right by 0-7 bits )
-@right-shift0 ( x** n^ -> x<<n )
+@rshift32-0 ( x** n^ -> x<<n )
         STHk  SFT                      ;sh/z3 STA  ( write z3 )
     #00 STHkr SFT2 #00 ;sh/z3 LDA ORA2 ;sh/z2 STA2 ( write z2,z3 )
     #00 STHkr SFT2 #00 ;sh/z2 LDA ORA2 ;sh/z1 STA2 ( write z1,z2 )
@@ -189,7 +192,7 @@
     RTN
 
 ( shift right by 8-15 bits )
-@right-shift1 ( x** n^ -> x<<n )
+@rshift32-1 ( x** n^ -> x<<n )
     #08 SUB STH POP 
         STHkr SFT                      ;sh/z3 STA  ( write z3 )
     #00 STHkr SFT2 #00 ;sh/z3 LDA ORA2 ;sh/z2 STA2 ( write z2,z3 )
@@ -198,7 +201,7 @@
     RTN
 
 ( shift right by 16-23 bits )
-@right-shift2 ( x** n^ -> x<<n )
+@rshift32-2 ( x** n^ -> x<<n )
     #10 SUB STH POP2
         STHkr SFT                      ;sh/z3 STA ( write z3 )
     #00 STHr  SFT2 #00 ;sh/z3 LDA ORA2            ( compute z2,z3 )
@@ -206,22 +209,22 @@
     RTN
 
 ( shift right by 16-23 bits )
-@right-shift3 ( x** n^ -> x<<n )
+@rshift32-3 ( x** n^ -> x<<n )
     #18 SUB STH POP2 POP ( x0 )
     #00 SWP #0000 SWP2 ( 00 00 00 x0 )
     STHr SFT
     RTN
 
 ( x << n )
-@left-shift ( x** n^ -> x<<n )
-    DUP #08 LTH ;left-shift0 JCN2 ( x n )
-    DUP #10 LTH ;left-shift1 JCN2 ( x n )
-    DUP #18 LTH ;left-shift2 JCN2 ( x n )
-    ;left-shift3 JMP2 ( x n )    
+@lshift32 ( x** n^ -> x<<n )
+    DUP #08 LTH ;lshift32-0 JCN2 ( x n )
+    DUP #10 LTH ;lshift32-1 JCN2 ( x n )
+    DUP #18 LTH ;lshift32-2 JCN2 ( x n )
+    ;lshift32-3 JMP2 ( x n )
     RTN
 
 ( shift left by 0-7 bits )
-@left-shift0 ( x** n^ -> x<<n )
+@lshift32-0 ( x** n^ -> x<<n )
     #40 SFT STH ( stash n<<4 )
     #00 SWP STHkr SFT2                     ;sh/z2 STA2 ( store z2,z3 )
     #00 SWP STHkr SFT2 #00 ;sh/z2 LDA ORA2 ;sh/z1 STA2 ( store z1,z2 )
@@ -231,7 +234,7 @@
     RTN
 
 ( shift left by 8-15 bits )
-@left-shift1 ( x** n^ -> x<<n )
+@lshift32-1 ( x** n^ -> x<<n )
     #08 SUB #40 SFT STH ( stash [n-8]<<4 )
     #00 SWP STHkr SFT2                     ;sh/z1 STA2 ( store z1,z2 )
     #00 SWP STHkr SFT2 #00 ;sh/z1 LDA ORA2 ;sh/z0 STA2 ( store z0,z1 )
@@ -241,7 +244,7 @@
     RTN
 
 ( shift left by 16-23 bits )
-@left-shift2 ( x** n^ -> x<<n )
+@lshift32-2 ( x** n^ -> x<<n )
     #10 SUB #40 SFT STH ( stash [n-16]<<4 )
     #00 SWP STHkr SFT2                ;sh/z0 STA2 ( store z0,z1 )
             STHr  SFT  ;sh/z0 LDA ORA             ( calculate z0 )
@@ -250,7 +253,7 @@
     RTN
 
 ( shift left by 24-31 bits )
-@left-shift3 ( x** n^ -> x<<n )
+@lshift32-3 ( x** n^ -> x<<n )
     #18 SUB #40 SFT ( x0 x1 x2 x3 r=[n-24]<<4 )
     SFT ( x0 x1 x2 x3<<r )
     SWP2 POP2 SWP POP #0000 #00
@@ -364,11 +367,11 @@
 
     ( 1<<shift -> cur )
     #0000 #0001 ROT2 POP
-    ;left-shift JSR2 ;div32/cur1 STA2 ;div32/cur0 STA2
+    ;lshift32 JSR2 ;div32/cur1 STA2 ;div32/cur0 STA2
     
     ( div<<shift -> div )
     ;div32/div0 LDA2 ;div32/div1 LDA2 ROT2 POP
-    ;left-shift JSR2 ;div32/div1 STA2 ;div32/div0 STA2 
+    ;lshift32 JSR2 ;div32/div1 STA2 ;div32/div0 STA2 
 
      &loop
     ( if rem >= the current divisor, we can subtract it and add to quotient )
@@ -380,8 +383,8 @@
     ,&quo0 LDR2 ,&quo1 LDR2 ,&cur0 LDR2 ,&cur1 LDR2 ;add32 JSR2 ,&quo1 STR2 ,&quo0 STR2 ( quo += cur )
 
     &rem-lt
-    ,&div0 LDR2 ,&div1 LDR2 #01 ;right-shift JSR2 ,&div1 STR2 ,&div0 STR2 ( div >>= 1 )
-    ,&cur0 LDR2 ,&cur1 LDR2 #01 ;right-shift JSR2 ,&cur1 STR2 ,&cur0 STR2 ( cur >>= 1 )
+    ,&div0 LDR2 ,&div1 LDR2 #01 ;rshift32 JSR2 ,&div1 STR2 ,&div0 STR2 ( div >>= 1 )
+    ,&cur0 LDR2 ,&cur1 LDR2 #01 ;rshift32 JSR2 ,&cur1 STR2 ,&cur0 STR2 ( cur >>= 1 )
     ,&cur0 LDR2 ,&cur1 LDR2 ;non-zero32 JSR2 ,&loop JCN ( if cur>0, loop. else we're done )
     ,&quo0 LDR2 ,&quo1 LDR2 ( TODO: consider making this divmod32 )
     RTN
diff --git a/test-math32.tal b/test-math32.tal
index c1ac0f2..8bdd3c7 100644
--- a/test-math32.tal
+++ b/test-math32.tal
@@ -52,8 +52,8 @@ RTN
     ;buf LDA LIT '* EQU ;test-mul32 JCN2
     ;buf LDA LIT '- EQU ;test-sub32 JCN2
     ;buf LDA LIT '/ EQU ;test-div32 JCN2
-    ;buf LDA LIT 'L EQU ;test-left-shift JCN2
-    ;buf LDA LIT 'R EQU ;test-right-shift JCN2
+    ;buf LDA LIT 'L EQU ;test-lshift32 JCN2
+    ;buf LDA LIT 'R EQU ;test-rshift32 JCN2
     ;buf LDA LIT 'B EQU ;test-bitcount32 JCN2
     ;buf LDA LIT '& EQU ;test-and32 JCN2
     ;buf LDA LIT '| EQU ;test-or32 JCN2
@@ -123,8 +123,8 @@ RTN
 @test-mul32 ;mul32 ;binary-32-test JMP2
 @test-sub32 ;sub32 ;binary-32-test JMP2
 @test-div32 ;div32 ;binary-32-test JMP2
-@test-left-shift ;left-shift ;binary-32-8-32-test JMP2
-@test-right-shift ;right-shift ;binary-32-8-32-test JMP2
+@test-lshift32 ;lshift32 ;binary-32-8-32-test JMP2
+@test-rshift32 ;rshift32 ;binary-32-8-32-test JMP2
 @test-bitcount32 ;bitcount32 ;unary-32-8-test JMP2
 @test-and32 ;and32 ;binary-32-test JMP2
 @test-or32 ;or32  ;binary-32-test JMP2