Remove extraneous case-lambda comments + other misc docs fixes

core/src/file.sld

@@ -42,8 +42,6 @@
 
     (define (env-pair<? l r) (string<? (car l) (car r)))
 
-    ;; `(zfile CONTENTS [EXECUTABLE])`
-    ;;
     ;; Create a `<z-file>` object with given contents and optional `executable` flag.
     ;; The contents may either be a string or a `<zexp>`.
     (define zfile
@@ -54,8 +52,6 @@
     ;; Create a `<z-symlink>` record. The target may be any string, *or* a `<zexp>` containing one.
     (define (zsymlink target) (make-z-symlink target #f))
 
-    ;; `(zdir CONTENTS)`
-    ;;
     ;; Create a `<z-directory>` record. The contents is an alist of file name -> zfile/zsymlink/zdir.
     ;; For simplicity, one can also write e.g. `(zdir "key" value "key2" value)`.
     (define zdir
@@ -191,6 +187,7 @@
    
     ;; Serialize a file-like (`zfile`, `zsymlink`, `zdir`) to a `<store-path>`.
     ;; This function should not depend on the system of the builder.
+    ;;
     ;; TODO(puck): due to limitations, whatever you pass in ends up at `<store-path>/-` instead.
     (define (zfile->store val)
      (define cached

core/src/magic.sld

@@ -23,6 +23,7 @@
     zilch-magic-counters)
 
   (begin
+   ;; The daemon connection used by `(zilch magic)`.
    (define *daemon*
      (make-parameter
        (parameterize
@@ -33,16 +34,18 @@
                          (make-daemon-link in-port out-port))))))
    (daemon-wop-handshake (*daemon*))
 
+   ;; If set to `#f`, `store-path-for-ca-drv*` will not generate
+   ;; content-addressed derivations.
    (define *use-ca* (make-parameter #t))
    
-   ;; A vector of counters, counting the amount of derivations made, built, and read
+   ;; A vector of counters, counting the amount of derivations made, built, and IFD'd.
    (define zilch-magic-counters (vector 0 0 0))
    
    (define (increment-counter index)
      (vector-set! zilch-magic-counters index (+ 1 (vector-ref zilch-magic-counters index))))
  
    ;; Represents a reference to an output path of a derivation, or a source file.
-   ;; if output is "", drv is the store path to a source file.
+   ;; if `output` is `""`, `drv` is the store path to a source file.
    (define-record-type <store-path>
      (make-store-path drv output written)
      store-path?
@@ -59,11 +62,14 @@
    (define (store-path-path path)
      (derivation-output-path (cdr (assoc (store-path-output path) (derivation-outputs (store-path-drv path))))))
    
+   ;; Makes sure the derivation referenced by this store path exists in the daemon.
    (define (store-path-materialize path)
      (unless (store-path-written path)
        (write-drv-to-daemon (store-path-drv path))
        (set-store-path-written! path #t)))
    
+   ;; Returns the output path of this store path; fetching it from the daemon if
+   ;; the derivation is content-addressed.
    (define (store-path-realisation path)
      (define drv (store-path-drv path))
      (define output (store-path-output path))
@@ -89,7 +95,7 @@
             (daemon-wop-add-text-to-store (*daemon*) (string-append (derivation-name drv) ".drv") (get-output-string out) (derivation-path-references drv))))
        (make-store-path path "" #t))
 
-   ;; Returns a store path representing the text..
+   ;; Returns a store path representing the text.
    (define (store-path-for-text name text)
      (increment-counter 0)
      (define goal-path (make-text-path "sha256" (sha256 text) name '()))
@@ -140,6 +146,7 @@
      (define drv (make-ca-derivation name platform input-drvs input-srcs (zexp-evaluation-value collected-builder) (zexp-evaluation-value collected-env) outputs))
      (map (lambda (l) (cons (car l) (make-store-path drv (car l) #f))) (derivation-outputs drv)))
    
+   ;; Calls either `store-path-for-ca-drv` or `store-path-for-drv` depending on `*use-ca*`.
    (define (store-path-for-ca-drv* name platform builder env outputs)
      (if (*use-ca*) (store-path-for-ca-drv name platform builder env outputs)
                     (store-path-for-drv name platform builder env outputs)))

core/src/nix/drv.sld

@@ -424,7 +424,6 @@
           (bytevector-u8-set! buf len val)
           (set! len (+ 1 len))))
 
-    ;; `(derivation-read port name [read-drv-path])`
     ;; Reads a `<derivation>` from the `port`. If `read-drv-path` is set, will be used to read dependencies of this derivation,
     ;; rather than the default of reading from the local Nix store.
     (define derivation-read
@@ -490,8 +489,6 @@
         (write-bracket-list (lambda (l) (write-paren-list write-quoted-string (list (car l) (cdr l)))) (derivation-env drv))
         (write-u8 #x29)))
 
-    ;; `(derivation-serialize drv [port] [masked])`
-    ;;
     ;; Writes the derivation to the specified port, or current-output-port if none is supplied.
     ;; If masked is set, writes the derivation using the passed-in input derivations, rather than the default one.
     (define derivation-serialize

core/src/zexpr.sld

@@ -28,10 +28,10 @@
     ;; A zexp (concept inspired from Guix g-expressions) is represented as a
     ;; thunk that returns the quoted value, and writes the metadata (e.g. string context) necessary
     ;; into `++*zexp-context*++`.
-
+    ;;
-    ;; `(make-zexp thunk printer)`
+    ;; `(make-zexp thunk printer)` +
-    ;; `thunk` `(zexp-thunk zexp)` is the thunk called when evaluating the zexp.
+    ;; `thunk` `(zexp-thunk zexp)` is the thunk called when evaluating the zexp. +
-    ;; `printer` `(zexp-printer zexp)` is a thunk that is called with a port to print a representation of the zexp.
+    ;; `printer` `(zexp-printer zexp)` is a thunk that is called with a port to print a representation of the zexp. +
     (define-record-type <zexp>
       (make-zexp thunk printer)
       zexp?
@@ -62,8 +62,8 @@
 
     ;; The output of evaluating a `zexp`.
     ;;
-    ;; drvs is an alist of derivation path to a list of outputs used.
+    ;; `drvs` is an alist of derivation path to a list of outputs used. +
-    ;; srcs is a list of source store paths used.
+    ;; `srcs` is a list of source store paths used.
     (define-record-type <zexp-evaluation>
       (make-zexp-evaluation value drvs srcs)
       zexp-evaluation?
@@ -78,7 +78,7 @@
         (zexp-evaluation-srcs zeval)))
     
     ;; Adds any new items from a list of sources and an alist of derivations to the current `++*zexp-context*++`.
-    ;; drvs is an alist of derivation object to output. name.
+    ;; drvs is an alist of derivation object to output. name. +
     ;; TODO(puck): 'spensive?
     (define (zexp-context-register-items drvs srcs)
       (define ctx (*zexp-context*))
@@ -98,10 +98,10 @@
                            (for-each (lambda (output)
                                          (unless (member output (cdr pair)) (set-cdr! pair (cons output (cdr pair))))) (cdr drv)))) drvs)))
 
-    ;; The current zexp evaluation context. #f if not evaluating a zexp.
+    ;; The current zexp evaluation context. `#f` if not evaluating a zexp.
     (define *zexp-context* (make-parameter #f))
 
-    ; The actual zexp "quote" equivalent.
+    ; The actual zexp `quote` equivalent.
     (define-syntax zexp
       (syntax-rules (unquote)
         ((zexp-quote stuff) (make-zexp (lambda () (zexp-quote-inner stuff)) (lambda (port) (write (quote stuff) port))))))
@@ -112,7 +112,7 @@
     (define zexp-unquote-handlers '())
 
     ;; Add a procedure to be called when unquotingg an unknown value.
-    ;; This procedure should return #f if the value passed in cannot be unquoted by this handler.
+    ;; This procedure should return `#f` if the value passed in cannot be unquoted by this handler.
     (define (zexp-add-unquote-handler handler) (set! zexp-unquote-handlers (cons handler zexp-unquote-handlers)))
 
     (define (iter-unquote-handler val handlers)
@@ -141,7 +141,7 @@
                     (let ((nval (zexp-unquote val)))
                          (make-zexp-evaluation nval (zexp-context-drvs (*zexp-context*)) (zexp-context-srcs (*zexp-context*))))))
 
-    ;;; Returns a `<zexp>` that returns the same value as `<val>`, but adds the drvs/srcs as context.
+    ;; Returns a `<zexp>` that returns the same value as `<val>`, but adds the drvs/srcs as context.
     (define (zexp-with-injected-context val drvs srcs)
       (make-zexp (lambda () (zexp-context-register-items drvs srcs) ((zexp-thunk val))) (lambda (port) (write val port))))