read: document datum label

1 files changed, 8 insertions, 0 deletions

diff --git a/read.scm b/read.scm
index f6f50c7..099de01 100644
--- a/read.scm
+++ b/read.scm
@@ -545,6 +545,14 @@
 
 ;;; Readtable for the number part of a datum label / reference. A label
 ;;; looks like "#[NUMBER]=" and a reference looks like "#[NUMBER]#".
+;;; 
+;;; Datum label assignments #XXX=[DATUM] return DATUM.
+;;; Datum label references #XXX# return a DATUM-LABEL object, because
+;;; circular references must be resolved later. (With some trickery it
+;;; cold be resolved as soon as possible, but that requires knowledge of
+;;; what is complex data and what is an atom. This requires knowing all
+;;; possible values that the toplevel could read, which is not possible
+;;; because new items can be added to the toplevel.)
 (define readtable:datum-label-next
   (readtable:process
    (readtable:empty/default (readtable:error 'datum-label-next