--- gforth/assert.fs	1994/07/08 15:00:28	1.1
+++ gforth/assert.fs	1995/10/16 18:33:05	1.4
@@ -2,27 +2,35 @@
 
 \ !! factor out line number printing, share with debugging.fs
 
-variable assert-level \ all assertions above this level are turned off
+variable assert-level ( -- a-addr ) \ gforth
+\G all assertions above this level are turned off
 1 assert-level !
 
-: assertn ( n -- )
+: assertn ( n -- ) \ gforth assert-n
+    \ this is internal (it is not immediate)
     assert-level @ >
     if
 	POSTPONE (
     then ;
 
-: assert0( ( -- )
+: assert0( ( -- ) \ gforth assert-zero
+    \G important assertions that should always be turned on
     0 assertn ; immediate
-: assert1( ( -- )
+: assert1( ( -- ) \ gforth assert-one
+    \G normal assertions; turned on by default
     1 assertn ; immediate
-: assert2( ( -- )
+: assert2( ( -- ) \ gforth assert-two
+    \G debugging assertions
     2 assertn ; immediate
-: assert3( ( -- )
+: assert3( ( -- ) \ gforth assert-three
+    \G slow assertions that you may not want to turn on in normal debugging;
+    \G you would turn them on mainly for thorough checking
     3 assertn ; immediate
-: assert( ( -- )
+: assert( ( -- ) \ gforth
+    \G equivalent to assert1(
     POSTPONE assert1( ; immediate
 
-: (endassert) ( flag -- )
+: (endassert) ( flag -- ) \ gforth-internal
     \ three inline arguments
     if
 	r> 3 cells + >r EXIT
@@ -33,5 +41,6 @@ variable assert-level \ all assertions a
 	true abort" assertion failed" \ !! or use a new throw code?
     then ;
 
-: ) ( -- )
+: ) ( -- ) \ gforth	close-paren
+    \G end an assertion
     POSTPONE (endassert) loadfilename 2@ 2, loadline @ , ; immediate