Document the library words

bjforth/src/main/forth/bjForth.forth

@@ -1,27 +1,77 @@
 ###################################################################################################
+# \n ( -- s )
+#
+# New line constant.
+###################################################################################################
+
 : \n
  ." 
  ".
 ;
 
 ###################################################################################################
-: CR \n EMIT ;
+# CR ( -- )
+# Prints a new line.
+###################################################################################################
+
+: CR 
+  \n EMIT 
+;
 
 ###################################################################################################
-: BL ."   ". ;
+# BL ( -- s )
+#
+# Whitespace constant.
+###################################################################################################
 
+: BL 
+  ."   ". 
+;
+
+###################################################################################################
+# SPACE ( -- )
+#
+# Prints a whitespace
 ###################################################################################################
+
 : SPACE BL EMIT ;
 
 ###################################################################################################
-### ( a - b )
+# NEGATE ( a -- b ) 
+# 
+# Negates the top of stack.
+###################################################################################################
+
 : NEGATE 0 SWAP - ;
 
 ###################################################################################################
+# TRUE ( -- 1 )
+#
+# Truthy constant.
+###################################################################################################
+
 : TRUE  1 ;
+
+###################################################################################################
+# FALSE ( -- 0 )
+#
+# Truthy constant.
+###################################################################################################
+
 : FALSE 0 ;
+
+###################################################################################################
+# NOT ( b -- a )
+#
+# Logically negates the truthy value at the top of stack.
+###################################################################################################
+
 : NOT   0= ;
 
+###################################################################################################
+# [COMPILE] ( -- )
+#
+# Compiles a word in compiling word as if it were in immediate mode.
 ###################################################################################################
 : [COMPILE] IMMEDIATE
   WORD
@@ -31,6 +81,25 @@
 ;
 
 ###################################################################################################
+# <condition> IF <repeated code if condition is met> ELSE <repeated code otherwise> THEN
+#
+# Basic conditional.
+#
+# ```forth
+# : IS-10?
+#   10 = IF 
+#     ." It's 10! ". PRINTLN 
+#    ELSE 
+#      ." Nope ". PRINTLN 
+#    THEN 
+# ;
+# 10 IS-10?
+# It's 10!
+# 20 IS-10?
+# Nope
+# ```
+###################################################################################################
+
 : IF IMMEDIATE
   ' 0BRANCH ,  
   HERE        
@@ -56,31 +125,101 @@
 ;
 
 ###################################################################################################
+# Basic conditional.
+#
+# ```forth
+# : IS-10? 
+#   10 = UNLESS 
+#     ." Nope ". PRINTLN 
+#   ELSE 
+#     ." It's 10 ". PRINTLN 
+#   THEN 
+# ;
+# 10 IS-10?
+# It's 10
+# 20 IS-10?
+# Nope
+# ```
+###################################################################################################
+
 : UNLESS IMMEDIATE
   ' NOT ,
   [COMPILE] IF
 ;
 
 ###################################################################################################
+
 : BEGIN IMMEDIATE
   HERE
 ;
 
 ###################################################################################################
+# Basic looping construct.
+#
+# ```forth
+# : COUNT-TO-9
+#  1
+#  BEGIN
+#  PRINT SPACE
+#  1+
+#  DUP 10 = UNTIL
+# ;
+# COUNT-TO-9
+# 1 2 3 4 5 6 7 8 9
+# ```
+###################################################################################################
+
 : UNTIL IMMEDIATE
   ' 0BRANCH ,
   HERE SWAP -
   ,
 ;
 
 ###################################################################################################
+# An infinite loop that can be only returned from via `EXIT`.
+#
+# ```forth
+# : COUNT-TO-9
+#   1 
+#   BEGIN
+#   PRINT SPACE
+#   1+
+#   DUP 10 = IF
+#     EXIT
+#   THEN
+#   AGAIN 
+# ;
+# COUNT-TO-9
+# 1 2 3 4 5 6 7 8 9
+# ```forth
+###################################################################################################
+
 : AGAIN IMMEDIATE
   ' BRANCH ,
   HERE SWAP -
   ,
 ;
 
 ###################################################################################################
+# Basic looping construct. 
+#
+# BEGIN condition WHILE loop-part REPEAT
+#
+# ```forth
+# : COUNT-TO-9
+# 1
+# BEGIN
+#   DUP 10 <>
+# WHILE
+#   PRINT SPACE
+#   1+
+# REPEAT
+# ;
+# COUNT-TO-9
+# 1 2 3 4 5 6 7 8 9
+# ```
+###################################################################################################
+
 : WHILE IMMEDIATE
   ' 0BRANCH ,
   HERE
@@ -98,23 +237,59 @@
 ;
 
 ###################################################################################################
-### ( x y -- y ) 
+# NIP ( x y -- y )
+#
+# Drops the 2nd element of the stack.
+#
+# ```forth
+# 10 20 NIP .S
+# java.lang.Integer<20>
+# ```
+###################################################################################################
+
 : NIP 
   SWAP DROP 
 ;
 
 ###################################################################################################
-### ( x y -- y x y )
+# TUCK ( x y -- y x y )
+#
+# ```forth
+# 10 20 TUCK .S
+# java.lang.Integer<20>
+# java.lang.Integer<10>
+# java.lang.Integer<20>
+###################################################################################################
+
 : TUCK  
   SWAP OVER 
 ;
 
 ###################################################################################################
-### ( x_u ... x_1 x_0 u -- x_u ... x_1 x_0 x_u )
-: PICK 
+# PICK ( x_u ... x_1 x_0 u -- x_u ... x_1 x_0 x_u )
+#
+# Copies the `u`th element of the stack to the top.
+#
+# ```forth
+# 10 20 30 40 1 PICK
+# .S
+# java.lang.Integer<10>
+# java.lang.Integer<20>
+# java.lang.Integer<30>
+# java.lang.Integer<40>
+# java.lang.Integer<20>
+# ```
+###################################################################################################
+
+: PICK
   1+
   DSP@@
 ;
+
+###################################################################################################
+# (
+#
+# Immediate word that treats `(` and `)` as comment indicators.
 ###################################################################################################
 
 : ( IMMEDIATE
@@ -133,6 +308,10 @@
   DROP
 ;
 
+###################################################################################################
+# /MOD ( x y - quotient remainder )
+#
+# Leaves the quotient and remainder of `y / x` on the stack.
 ###################################################################################################
 
 : /MOD ( x y - quotient remainder )
@@ -144,6 +323,10 @@
   MOD 
 ;
 
+###################################################################################################
+# SPACES ( n -- )
+#
+# Prints `n` whitespaces.
 ###################################################################################################
 
 : SPACES ( n -- )
@@ -156,12 +339,22 @@
   DROP
 ;
 
+###################################################################################################
+# DECIMAL ( -- ) 
+# 
+# Sets the value of `BASE` to 10.
 ###################################################################################################
 
 : DECIMAL ( -- ) 
   10 !BASE 
 ;
 
+###################################################################################################
+# HEX ( -- ) 
+# 
+# Sets the value of `BASE` to 16.
+###################################################################################################
+
 : HEX ( -- ) 
   16 !BASE 
 ;