zone.lisp: Improve commentary regarding the syntax of record forms.

[zone] / zone.lisp

diff --git a/zone.lisp b/zone.lisp
index b0e55822e55675344e9f4248d38b2da8fe14ebd6..38c79f09f57be9df3187c41ae43d6130d24147e5 100644 (file)
--- a/zone.lisp
+++ b/zone.lisp
@@ -253,7 +253,25 @@ (defmacro preferred-subnet-case (&body clauses)
 (defun zone-process-records (rec ttl func)
   "Sort out the list of records in REC, calling FUNC for each one.
 
-   TTL is the default time-to-live for records which don't specify one."
+   TTL is the default time-to-live for records which don't specify one.
+
+   The syntax is a little fiddly to describe.  It operates relative to a
+   subzone name NAME.
+
+   ZONE-RECORD: RR | TTL | SUBZONE
+       The body of a zone form is a sequence of these.
+
+   TTL: :ttl INTEGER
+       Sets the TTL for subsequent RRs in this zone or subzone.
+
+   RR: SYMBOL DATA
+       Adds a record for the current NAME; the SYMBOL denotes the record
+       type, and the DATA depends on the type.
+
+   SUBZONE: (LABELS ZONE-RECORD*)
+       Defines a subzone.  The LABELS is either a list of labels, or a
+       singleton label.  For each LABEL, evaluate the ZONE-RECORDs relative
+       to LABEL.NAME.  The special LABEL `@' is a no-op."
   (labels ((sift (rec ttl)
             (collecting (top sub)
               (loop
@@ -515,6 +533,9 @@        (defun ,func (,prefix ,zname ,data ,ttl ,col)
          ',type)))))
 
 (defun zone-parse-records (zone records)
+  "Parse the body of a zone form.
+
+   ZONE is the zone object; RECORDS is the body of the form."
   (let ((zname (zone-name zone)))
     (with-collection (rec)
        (flet ((parse-record (zr)