update documentation

1 files changed, 12 insertions, 12 deletions

diff --git a/market/blocks.scm b/market/blocks.scm
index 0d0b7d2..641d4ab 100644
--- a/market/blocks.scm
+++ b/market/blocks.scm
@@ -20,20 +20,20 @@
   ;; 
   ;; DATA is arbitrary data associated with the node.
   ;; 
-  ;; (CONTINUES LINE) is a procedure that takes a line and returns either
+  ;; (CONTINUES NODE LINE) is a procedure that takes a node and
+  ;; the current line and returns
   ;; 
   ;; 1) `#f`, denoting that the line does not continue the block, or
   ;; 2) the rest of the after consuming the continuation text of the block.
   ;; 
-  ;; ALLOWED-INSIDE is a procedure that takes a line and returns
+  ;; (ALLOWED-INSIDE NODE LINE) is a procedure that takes the current node
+  ;; and the current line and returns
   ;; 
   ;; 1) `#f`, meaning that the line does not start a new node that can be
   ;;    started inside of the block, or
-  ;; 2) (VALUES NEW-CHILD NEW-NODE LINE), which returns
-  ;;    
-  ;;    1) The new child node,
-  ;;    2) The node from which to start processing the rest of the line,
-  ;;    3) the rest of the line.
+  ;; 2) (VALUES NEW-NODE LINE), which are arguments to a tail-called
+  ;;    invocation of `parse-line-to-node!`. The parsing will continue at
+  ;;    `new-node` with the line `line`.
   ;; 
   ;; CHILDREN is an SRFI-117 queue of child blocks of the node.
   ;; 
@@ -88,7 +88,8 @@
     ;; Handle insertion of a new line when the active child is a paragraph.
     ;; 
     ;; If the new line is the start of a block allowed in `node` then close
-    ;; `child` and add a new child. Otherwise, add to the paragraph.
+    ;; `child` and add a new child. If the line is empty, put in a paragraph
+    ;; break. Otherwise, add to the paragraph.
     (cond
       ((allowed-inside node line) first-arg => parse-line-to-node!)
       ((empty-line? line) (close-active-children! node))
@@ -97,8 +98,9 @@
     ;; Handle insertion of a new line when the active child is a block.
     ;; 
     ;; Check if `line` continues `child`. If not, check if `line` is
-    ;; allowed after `child` in this node. Finally, check if `line` is
-    ;; allowed inside this node. If not, add the line as a paragraph.
+    ;; allowed after `child` in this node. If not, check if `line` is
+    ;; allowed inside this node. If not, check if line is a paragraph
+    ;; break. If not, add the line as a paragraph.
     (cond
       ((continues active-child line) => (cut parse-line-to-node! active-child <>))
       ((allowed-inside node line) first-arg => (cut parse-line-to-node! <...>))
@@ -117,8 +119,6 @@
     (add-new-child! node new-child #t)))
 
 (define (parse-line-to-node! node line)
-  ;;  NODE.
-  ;; 
   ;; If there is an active node, either add the line to the node or start a
   ;; new node. If there is no active node, start a new node, either by
   ;; starting a new block or by starting a new paragraph.