4808 - clean up comments in all subx files

12 files changed, 83 insertions, 80 deletions

diff --git a/subx/examples/ex1.subx b/subx/examples/ex1.subx
index 3371cd75..89d331ab 100644
--- a/subx/examples/ex1.subx
+++ b/subx/examples/ex1.subx
@@ -1,4 +1,4 @@
-## first program: same as https://www.muppetlabs.com/~breadbox/software/tiny/teensy.html
+# First program: same as https://www.muppetlabs.com/~breadbox/software/tiny/teensy.html
 # Just return 42.
 #
 # To run (from the subx directory):
@@ -10,8 +10,8 @@
 
 == code
 
+# syscall(exit, 42)
 bb/copy-to-EBX  2a/imm32  # 42 in hex
-# exit(EBX)
 b8/copy-to-EAX  1/imm32/exit
 cd/syscall  0x80/imm8
 
diff --git a/subx/examples/ex10.subx b/subx/examples/ex10.subx
index 936edb08..69e7c2ec 100644
--- a/subx/examples/ex10.subx
+++ b/subx/examples/ex10.subx
@@ -1,4 +1,4 @@
-## String comparison: return 1 iff the two args passed in at the commandline are equal.
+# String comparison: return 1 iff the two args passed in at the commandline are equal.
 #
 # To run (from the subx directory):
 #   $ subx translate examples/ex10.subx -o examples/ex10
@@ -20,15 +20,14 @@
 #         ...
     # . prolog
     89/copy                         3/mod/direct    5/rm32/EBP    .           .             .           4/r32/ESP   .               .                 # copy ESP to EBP
-    # . . call argv-equal(argv[1], argv[2])
-    # push argv[2]
+    # argv-equal(argv[1], argv[2])
+    # . . push argv[2]
     ff          6/subop/push        1/mod/*+disp8   4/rm32/sib    5/base/EBP  4/index/none  .           .           0xc/disp8       .                 # push *(EBP+12)
-    # push argv[1]
+    # . . push argv[1]
     ff          6/subop/push        1/mod/*+disp8   4/rm32/sib    5/base/EBP  4/index/none  .           .           0x8/disp8       .                 # push *(EBP+8)
     # . . call
     e8/call argv-equal/disp32
-    # exit(EAX)
-$exit:
+    # syscall(exit, EAX)
     89/copy                         3/mod/direct    3/rm32/EBX    .           .             .           0/r32/EAX   .               .                 # copy EAX to EBX
     b8/copy-to-EAX  1/imm32
     cd/syscall  0x80/imm8
diff --git a/subx/examples/ex11.subx b/subx/examples/ex11.subx
index 253b91ab..e2628c39 100644
--- a/subx/examples/ex11.subx
+++ b/subx/examples/ex11.subx
@@ -1,4 +1,4 @@
-## Null-terminated vs length-prefixed ascii strings.
+# Null-terminated vs length-prefixed ascii strings.
 #
 # By default we create strings with a 4-byte length prefix rather than a null suffix.
 # However we still need null-prefixed strings when interacting with the Linux
@@ -108,7 +108,7 @@ $kernel-string-equal:end:
     5d/pop-to-EBP
     c3/return
 
-## tests
+# - tests
 
 test-compare-null-kernel-string-with-empty-array:
     # EAX = kernel-string-equal(Null-kernel-string, "")
@@ -119,7 +119,7 @@ test-compare-null-kernel-string-with-empty-array:
     e8/call  kernel-string-equal/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
-    # . . call check-ints-equal(EAX, 1, msg)
+    # check-ints-equal(EAX, 1, msg)
     # . . push args
     68/push  "F - test-compare-null-kernel-string-with-empty-array"/imm32
     68/push  1/imm32/true
@@ -139,7 +139,7 @@ test-compare-null-kernel-string-with-non-empty-array:
     e8/call  kernel-string-equal/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
-    # . . call check-ints-equal(EAX, 0, msg)
+    # check-ints-equal(EAX, 0, msg)
     # . . push args
     68/push  "F - test-compare-null-kernel-string-with-non-empty-array"/imm32
     68/push  0/imm32/false
@@ -159,7 +159,7 @@ test-compare-kernel-string-with-equal-array:
     e8/call  kernel-string-equal/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
-    # . . call check-ints-equal(EAX, 1, msg)
+    # check-ints-equal(EAX, 1, msg)
     # . . push args
     68/push  "F - test-compare-kernel-string-with-equal-array"/imm32
     68/push  1/imm32/true
@@ -179,7 +179,7 @@ test-compare-kernel-string-with-inequal-array:
     e8/call  kernel-string-equal/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
-    # . . call check-ints-equal(EAX, 0, msg)
+    # check-ints-equal(EAX, 0, msg)
     # . . push args
     68/push  "F - test-compare-kernel-string-with-equal-array"/imm32
     68/push  0/imm32/false
@@ -199,7 +199,7 @@ test-compare-kernel-string-with-empty-array:
     e8/call  kernel-string-equal/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
-    # . . call check-ints-equal(EAX, 0)
+    # check-ints-equal(EAX, 0)
     # . . push args
     68/push  "F - test-compare-kernel-string-with-equal-array"/imm32
     68/push  0/imm32/false
@@ -219,7 +219,7 @@ test-compare-kernel-string-with-shorter-array:
     e8/call  kernel-string-equal/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
-    # . . call check-ints-equal(EAX, 0)
+    # check-ints-equal(EAX, 0)
     # . . push args
     68/push  "F - test-compare-kernel-string-with-shorter-array"/imm32
     68/push  0/imm32/false
@@ -239,7 +239,7 @@ test-compare-kernel-string-with-longer-array:
     e8/call  kernel-string-equal/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
-    # . . call check-ints-equal(EAX, 0)
+    # check-ints-equal(EAX, 0)
     # . . push args
     68/push  "F - test-compare-kernel-string-with-longer-array"/imm32
     68/push  0/imm32/false
@@ -250,7 +250,7 @@ test-compare-kernel-string-with-longer-array:
     81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add to ESP
     c3/return
 
-## helpers
+# - helpers
 
 # print msg to stderr if a != b, otherwise print "."
 check-ints-equal:  # (a : int, b : int, msg : (address array byte)) -> boolean
@@ -263,19 +263,19 @@ check-ints-equal:  # (a : int, b : int, msg : (address array byte)) -> boolean
     # load args into EAX, EBX and ECX
     8b/copy                         1/mod/*+disp8   4/rm32/sib    5/base/EBP  4/index/none  .           0/r32/EAX   0x8/disp8       .                 # copy *(EBP+8) to EAX
     8b/copy                         1/mod/*+disp8   4/rm32/sib    5/base/EBP  4/index/none  .           3/r32/EBX   0xc/disp8       .                 # copy *(EBP+12) to EBX
-    # if EAX == b/EBX
+    # if EAX == b/EBX print('.') and return
     39/compare                      3/mod/direct    0/rm32/EAX    .           .             .           3/r32/EBX   .               .                 # compare EAX and EBX
     75/jump-if-unequal  $check-ints-equal:else/disp8
-    # print('.')
+    # . write-stderr('.')
     # . . push args
     68/push  "."/imm32
     # . . call
     e8/call  write-stderr/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
-    # return
+    # . return
     eb/jump  $check-ints-equal:end/disp8
-    # else:
+    # otherwise print(msg)
 $check-ints-equal:else:
     # copy msg into ECX
     8b/copy                         1/mod/*+disp8   4/rm32/sib    5/base/EBP  4/index/none  .           1/r32/ECX   0x10/disp8       .                # copy *(EBP+16) to ECX
@@ -312,15 +312,15 @@ write-stderr:  # s : (address array byte) -> <void>
     52/push-EDX
     53/push-EBX
     # syscall(write, 2/stderr, (data) s+4, (size) *s)
-    # fd = 2 (stderr)
+    # . . fd = 2 (stderr)
     bb/copy-to-EBX  2/imm32
-    # x = s+4
+    # . . x = s+4
     8b/copy                         1/mod/*+disp8   4/rm32/sib    5/base/EBP  4/index/none  .           1/r32/ECX   8/disp8         .                 # copy *(EBP+8) to ECX
     81          0/subop/add         3/mod/direct    1/rm32/ECX    .           .             .           .           .               4/imm32           # add to ECX
-    # size = *s
+    # . . size = *s
     8b/copy                         1/mod/*+disp8   4/rm32/sib    5/base/EBP  4/index/none  .           2/r32/EDX   8/disp8         .                 # copy *(EBP+8) to EDX
     8b/copy                         0/mod/indirect  2/rm32/EDX    .           .             .           2/r32/EDX   .               .                 # copy *EDX to EDX
-    # syscall
+    # . . syscall
     b8/copy-to-EAX  4/imm32/write
     cd/syscall  0x80/imm8
     # . restore registers
@@ -328,7 +328,7 @@ write-stderr:  # s : (address array byte) -> <void>
     5a/pop-to-EDX
     59/pop-to-ECX
     58/pop-to-EAX
-    # end
+    # . end
     89/copy                         3/mod/direct    4/rm32/ESP    .           .             .           5/r32/EBP   .               .                 # copy EBP to ESP
     5d/pop-to-EBP
     c3/return
diff --git a/subx/examples/ex12.subx b/subx/examples/ex12.subx
index 565c8d50..3b101379 100644
--- a/subx/examples/ex12.subx
+++ b/subx/examples/ex12.subx
@@ -1,4 +1,4 @@
-## example showing mmap syscall
+# Example showing mmap syscall.
 # Create a new segment using mmap, save the address, write to it.
 #
 # To run (from the subx directory):
@@ -16,7 +16,7 @@
     b8/copy-to-EAX  0x5a/imm32/mmap
     cd/syscall  0x80/imm8
 
-    # store to *EAX
+    # write to *EAX to check that we have access to the newly-allocated segment
     c7/copy                         0/mod/direct    0/rm32/EAX    .           .             .           .           .               0x34/imm32              # copy to *EAX
 
     # syscall(exit, EAX)
diff --git a/subx/examples/ex2.subx b/subx/examples/ex2.subx
index f7be9b65..80833894 100644
--- a/subx/examples/ex2.subx
+++ b/subx/examples/ex2.subx
@@ -1,4 +1,4 @@
-## add 1 and 1, and return the result in the exit code
+# Add 1 and 1, and return the result in the exit code.
 #
 # To run (from the subx directory):
 #   $ subx translate examples/ex2.subx -o examples/ex2
@@ -9,9 +9,11 @@
 
 == code
 
+# EBX = 1
 bb/copy-to-EBX  1/imm32
+# increment EBX
 43/inc-EBX
-# exit(EBX)
+# syscall(exit, EBX)
 b8/copy-to-EAX  1/imm32
 cd/syscall  0x80/imm8
 
diff --git a/subx/examples/ex3.subx b/subx/examples/ex3.subx
index b6e21698..a89ec99c 100644
--- a/subx/examples/ex3.subx
+++ b/subx/examples/ex3.subx
@@ -1,4 +1,4 @@
-## add the first 10 numbers, and return the result in the exit code
+# Add the first 10 numbers, and return the result in the exit code.
 #
 # To run (from the subx directory):
 #   $ subx translate examples/ex3.subx -o examples/ex3
@@ -29,7 +29,7 @@ $loop:
     eb/jump  $loop/disp8
 
 $exit:
-    # exit(EBX)
+    # syscall(exit, EBX)
     b8/copy-to-EAX  1/imm32
     cd/syscall  0x80/imm8
 
diff --git a/subx/examples/ex4.subx b/subx/examples/ex4.subx
index 2fd15cd7..964d4a60 100644
--- a/subx/examples/ex4.subx
+++ b/subx/examples/ex4.subx
@@ -1,4 +1,4 @@
-## read a character from stdin, save it to a global, write it to stdout
+# Read a character from stdin, save it to a global, write it to stdout.
 #
 # To run (from the subx directory):
 #   $ subx translate examples/ex4.subx -o examples/ex4
@@ -7,24 +7,24 @@
 == code
 
 # syscall(read, stdin, X, 1)
-    # fd = 0 (stdin)
+# . fd = 0 (stdin)
 bb/copy-to-EBX  0/imm32
-    # initialize X (location to write result to)
+# . data = X (location to write result to)
 b9/copy-to-ECX  X/imm32
-    # size = 1 character
+# . size = 1 character
 ba/copy-to-EDX  1/imm32
-    # syscall
+# . syscall
 b8/copy-to-EAX  3/imm32/read
 cd/syscall  0x80/imm8
 
 # syscall(write, stdout, X, 1)
-    # fd = 1 (stdout)
+# . fd = 1 (stdout)
 bb/copy-to-EBX  1/imm32
-    # initialize X (location to read from)
+# . initialize X (location to read from)
 b9/copy-to-ECX  X/imm32
-    # size = 1 character
+# . size = 1 character
 ba/copy-to-EDX  1/imm32
-    # syscall
+# . syscall
 b8/copy-to-EAX  4/imm32/write
 cd/syscall  0x80/imm8
 
diff --git a/subx/examples/ex5.subx b/subx/examples/ex5.subx
index 136c177b..5028568c 100644
--- a/subx/examples/ex5.subx
+++ b/subx/examples/ex5.subx
@@ -1,4 +1,4 @@
-## read a character from stdin, save it to a local on the stack, write it to stdout
+# Read a character from stdin, save it to a local on the stack, write it to stdout.
 #
 # To run (from the subx directory):
 #   $ subx translate examples/ex5.subx -o examples/ex5
@@ -14,24 +14,24 @@
     81          5/subop/subtract    3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # subtract from ESP
 
     # syscall(read, stdin, x, 1)
-    # fd = 0 (stdin)
+    # . fd = 0 (stdin)
     bb/copy-to-EBX  0/imm32
-    # initialize x (location to write result to)
+    # . data = x (location to write result to)
     8d/copy-address                 1/mod/*+disp8   4/rm32/sib    4/base/ESP  4/index/none              1/r32/ECX   4/disp8         .                 # copy ESP+4 to ECX
-    # size = 1 character
+    # . size = 1 character
     ba/copy-to-EDX  1/imm32
-    # syscall
+    # . syscall
     b8/copy-to-EAX  3/imm32/read
     cd/syscall  0x80/imm8
 
     # syscall(write, stdout, x, 1)
-    # fd = 1 (stdout)
+    # . fd = 1 (stdout)
     bb/copy-to-EBX  1/imm32
-    # initialize x (location to read from)
+    # . data = x (location to read from)
     8d/copy-address                 1/mod/*+disp8   4/rm32/sib    4/base/ESP  4/index/none              1/r32/ECX   4/disp8         .                 # copy ESP+4 to ECX
-    # size = 1 character
+    # . size = 1 character
     ba/copy-to-EDX  1/imm32
-    # syscall
+    # . syscall
     b8/copy-to-EAX  4/imm32/write
     cd/syscall  0x80/imm8
 
diff --git a/subx/examples/ex6.subx b/subx/examples/ex6.subx
index fc266a3a..8b3637f6 100644
--- a/subx/examples/ex6.subx
+++ b/subx/examples/ex6.subx
@@ -1,4 +1,4 @@
-## print out a (global variable) string to stdout
+# Print out a (global variable) string to stdout.
 #
 # To run (from the subx directory):
 #   $ subx translate examples/ex6.subx -o examples/ex6
@@ -10,14 +10,14 @@
 # . op          subop               mod             rm32          base        index         scale       r32
 # . 1-3 bytes   3 bits              2 bits          3 bits        3 bits      3 bits        2 bits      2 bits      0/1/2/4 bytes   0/1/2/4 bytes
 
-    # syscall(write, stdout, X, size)
-    # fd = 1 (stdout)
+    # syscall(write, stdout, X, Size)
+    # . fd = 1 (stdout)
     bb/copy-to-EBX  1/imm32
-    # initialize X (location to write result to)
+    # . initialize X (location to write result to)
     b9/copy-to-ECX  X/imm32
-    # initialize size
-    8b/copy                         0/mod/indirect  5/rm32/.disp32            .             .           2/r32/EDX   Size/disp32     .                 # copy *size to EDX
-    # syscall
+    # . initialize Size
+    8b/copy                         0/mod/indirect  5/rm32/.disp32            .             .           2/r32/EDX   Size/disp32     .                 # copy *Size to EDX
+    # . syscall
     b8/copy-to-EAX  4/imm32/write
     cd/syscall  0x80/imm8
 
diff --git a/subx/examples/ex7.subx b/subx/examples/ex7.subx
index 3650817d..e28ff89b 100644
--- a/subx/examples/ex7.subx
+++ b/subx/examples/ex7.subx
@@ -1,4 +1,5 @@
-## example showing file syscalls
+# Example showing file syscalls.
+#
 # Create a file, open it for writing, write a character to it, close it, open
 # it for reading, read a character from it, close it, delete it, and return
 # the character read.
@@ -32,20 +33,20 @@
     89/copy                         0/mod/indirect  3/rm32/EBX    .           .             .           0/r32/EAX   .               .                       # copy EAX to *EBX
 
     # syscall(write, Stream, "a", 1)
-    # load stream
+    # . load stream
     bb/copy-to-EBX  Stream/imm32
     8b/copy                         0/mod/indirect  3/rm32/EBX    .           .             .           3/r32/EBX   .               .                       # copy *EBX to EBX
-    #
+    # .
     b9/copy-to-ECX  A/imm32
     ba/copy-to-EDX  1/imm32/size
     b8/copy-to-EAX  4/imm32/write
     cd/syscall  0x80/imm8
 
     # syscall(close, Stream)
-    # load stream
+    # . load stream
     bb/copy-to-EBX  Stream/imm32
     8b/copy                         0/mod/indirect  3/rm32/EBX    .           .             .           3/r32/EBX   .               .                       # copy *EBX to EBX
-    #
+    # .
     b8/copy-to-EAX  6/imm32/close
     cd/syscall  0x80/imm8
 
@@ -55,22 +56,22 @@
     ba/copy-to-EDX  0x180/imm32/fixed-perms
     b8/copy-to-EAX  5/imm32/open
     cd/syscall  0x80/imm8
-    # save Stream
+    # . save Stream
     bb/copy-to-EBX  Stream/imm32
     89/copy                         0/mod/indirect  3/rm32/EBX    .           .             .           0/r32/EAX   .               .                       # copy EAX to *EBX
 
     # syscall(read, Stream, B, 1)
-    # load stream
+    # . load stream
     bb/copy-to-EBX  Stream/imm32
     8b/copy                         0/mod/indirect  3/rm32/EBX    .           .             .           3/r32/EBX   .               .                       # copy *EBX to EBX
-    #
+    # .
     b9/copy-to-ECX  B/imm32
     ba/copy-to-EDX  1/imm32/size
     b8/copy-to-EAX  3/imm32/read
     cd/syscall  0x80/imm8
 
     # syscall(close, Stream)
-    # load stream
+    # . load stream
     bb/copy-to-EBX  Stream/imm32
     8b/copy                         0/mod/indirect  3/rm32/EBX    .           .             .           3/r32/EBX   .               .                       # copy *EBX to EBX
     #
@@ -83,7 +84,7 @@
     cd/syscall  0x80/imm8
 
     # syscall(exit, b)
-    # load b
+    # . load b
     bb/copy-to-EBX  B/imm32
     8b/copy                         0/mod/indirect  3/rm32/EBX    .           .             .           3/r32/EBX   .               .                       # copy *EBX to EBX
     #
diff --git a/subx/examples/ex8.subx b/subx/examples/ex8.subx
index 410dfe08..6ec9eb3c 100644
--- a/subx/examples/ex8.subx
+++ b/subx/examples/ex8.subx
@@ -1,4 +1,4 @@
-## Example reading commandline arguments: compute length of first arg.
+# Example reading commandline arguments: compute length of first arg.
 #
 # To run (from the subx directory):
 #   $ subx translate examples/ex8.subx -o examples/ex8
@@ -21,7 +21,7 @@
 
     # . prolog
     89/copy                         3/mod/direct    5/rm32/EBP    .           .             .           4/r32/ESP   .               .                 # copy ESP to EBP
-    # . . call ascii-length(argv[1])
+    # EAX = ascii-length(argv[1])
     # . . push args
     ff          6/subop/push        1/mod/*+disp8   4/rm32/sib    5/base/EBP  4/index/none  .           .           0x8/disp8       .                 # push *(EBP+8)
     # . . call
@@ -34,13 +34,13 @@
     b8/copy-to-EAX  1/imm32/exit
     cd/syscall  0x80/imm8
 
-ascii-length:  # (s)
-    # initialize s (EDX)
+ascii-length:  # s : (address array byte) -> n/EAX
+    # EDX = s
     8b/copy                         1/mod/*+disp8   4/rm32/sib    4/base/ESP  4/index/none  .           2/r32/EDX   4/disp8         .                 # copy *(ESP+4) to EDX
-    # var result = 0 (EAX)
+    # var result/EAX = 0
     b8/copy-to-EAX  0/imm32
 $ascii-length-loop:
-    # var c = *s (ECX)
+    # var c/ECX = *s
     8a/copy                         0/mod/*         2/rm32/EDX    .           .             .           1/r32/ECX   .               .                 # copy byte at *EDX to lower byte of ECX
     # if c == '\0' break
     81          7/subop/compare     3/mod/direct    1/rm32/ECX    .           .             .           .           .               0/imm32           # compare ECX
@@ -52,7 +52,7 @@ $ascii-length-loop:
     # loop
     eb/jump  $ascii-length-loop/disp8
 $ascii-length-ret:
-    # return (result in EAX)
+    # return EAX
     c3/return
 
 # . . vim:nowrap:textwidth=0
diff --git a/subx/examples/ex9.subx b/subx/examples/ex9.subx
index 964151a2..ed4e6761 100644
--- a/subx/examples/ex9.subx
+++ b/subx/examples/ex9.subx
@@ -1,4 +1,5 @@
-## Example showing arg order on the stack.
+# Example showing arg order on the stack.
+#
 # Show difference between ascii codes of first letter of first arg and first
 # letter of second arg.
 #
@@ -23,16 +24,16 @@
 
     # . prolog
     89/copy                         3/mod/direct    5/rm32/EBP    .           .             .           4/r32/ESP   .               .                 # copy ESP to EBP
-    # . . call ascii-difference(argv[1], argv[2])
-    # push argv[2]
+    # ascii-difference(argv[1], argv[2])
+    # . . push argv[2]
     ff          6/subop/push        1/mod/*+disp8   4/rm32/sib    5/base/EBP  4/index/none  .           .           0xc/disp8       .                 # push *(EBP+12)
-    # push argv[1]
+    # . . push argv[1]
     ff          6/subop/push        1/mod/*+disp8   4/rm32/sib    5/base/EBP  4/index/none  .           .           0x8/disp8       .                 # push *(EBP+8)
     # . . call
     e8/call  ascii-difference/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
-    # exit(EAX)
+    # syscall(exit, EAX)
     89/copy                         3/mod/direct    3/rm32/EBX    .           .             .           0/r32/EAX   .               .                 # copy EAX to EBX
     b8/copy-to-EAX  1/imm32/exit
     cd/syscall  0x80/imm8