--- gforth/blocks.fs	1998/12/13 23:29:58	1.20
+++ gforth/blocks.fs	1999/03/29 22:52:27	1.23
@@ -58,7 +58,7 @@ block-cold
 Defer flush-blocks
 
 : open-blocks ( addr u -- ) \ gforth
-    \g use the file, whose name is given by @var{addr u}, as blocks file 
+    \g Use the file, whose name is given by @var{addr u}, as the blocks file.
     2dup open-fpath-file 0<>
     if
 	r/w bin create-file throw
@@ -70,7 +70,7 @@ Defer flush-blocks
     block-fid ! ;
 
 : use ( "file" -- ) \ gforth
-    \g use @var{file} as blocks file
+    \g Use @var{file} as the blocks file.
     name open-blocks ;
 
 \ the file is opened as binary file, since it either will contain text
@@ -83,7 +83,7 @@ Defer flush-blocks
     block-fid @ ;
 
 : block-position ( u -- ) \ block
-    \G positions the block file to the start of block u
+    \G Position the block file to the start of block @var{u}.
     1- chars/block chars um* get-block-fid reposition-file throw ;
 
 : update ( -- ) \ block
@@ -119,7 +119,10 @@ Defer flush-blocks
 : get-buffer ( n -- a-addr ) \ gforth
     buffers mod buffer-struct %size * block-buffers @ + ;
 
-: block ( u -- a-addr ) \ block
+: block ( u -- a-addr ) \ block- block
+  \G @var{u} identifies a block number. Assign a block buffer to @var{u},
+  \G make it the current block buffer and return its start
+  \G address, @var{a-addr}.
     dup 0= -35 and throw
     dup get-buffer >r
     dup r@ buffer-block @ <>
@@ -141,7 +144,11 @@ Defer flush-blocks
     \ reading in the block is unnecessary, but simpler
     block ;
 
-User scr 0 scr !
+User scr ( -- a-addr ) \ block-ext
+    \G USER VARIABLE @var{a-addr} is the address of a cell containing
+    \G the block number of the block most recently processed by
+    \G @code{LIST}.
+    0 scr !
 
 : updated?  ( n -- f ) \ gforth
     scr @ buffer
@@ -158,13 +165,15 @@ User scr 0 scr !
 	i 2 .r space scr @ block i 64 * chars + 64 type cr
     loop ;
 
-: (source)  ( -- addr len )
+: (source)  ( -- c-addr u )
   blk @ ?dup
   IF    block chars/block
   ELSE  tib #tib @
   THEN ;
 
-' (source) IS source
+' (source) IS source ( -- c-addr u ) \ core
+\G @var{c-addr} is the address of the input buffer and @var{u} is the
+\G number of characters in it.
 
 : load ( i*x n -- j*x ) \ block
   push-file
@@ -181,6 +190,9 @@ User scr 0 scr !
   1+ swap ?DO  I +load  LOOP ;
 
 : --> ( -- ) \ block- block
+    \G If this symbol is encountered whilst loading block @var{n},
+    \G discard the remainder of the block and load block @var{n+1}. Used
+    \G for chaining multiple blocks together as a single loadable unit.
     refill drop ; immediate
 
 : block-included ( addr u -- ) \ gforth
@@ -198,4 +210,6 @@ true constant block
 true constant block-ext
 set-current
 
-: bye  ['] flush catch drop bye ;
+: bye ( -- ) \ tools-ext
+  \G Return control to the host operating system (if any).
+  ['] flush catch drop bye ;