From d3ba6e7a9ffb0a7bfa34f400a8fa2f15baaeb001 Mon Sep 17 00:00:00 2001
From: colin <colin@cicadas.surf>
Date: Sun, 21 Jul 2024 08:10:50 -0700
Subject: Add: nicer docstring syntax

---
 def.lisp | 36 +++++++++++++++++++++++++++++-------
 1 file changed, 29 insertions(+), 7 deletions(-)

diff --git a/def.lisp b/def.lisp
index 4b0e613..6b517ed 100644
--- a/def.lisp
+++ b/def.lisp
@@ -32,7 +32,7 @@ reevaluated."
 
 SLOTS-AND-OPTIONS := (SLOT-SPEC1 ... SLOT-SPECN . CLASS-OPTIONS)
 
-Each SLOT-SPEC is a list of slot names followed by keyword slot
+Each SLOT-SPEC is a list of SLOT-NAME-SPECs followed by keyword slot
 options, E.g:
 
 (X Y Z :type real :initform 0)
@@ -42,6 +42,17 @@ Would expand into three slot definitions
 (Y :accessor Y :initarg :Y :type real :initform 0)
 (Z :accessor Z :initarg :Z :type real :initform 0)
 
+A SLOT-NAME-SPEC is either a symbol or a pair (NAME DOCSTRING). So the
+above might have been written:
+
+((X \"x coordinate\")
+ (Y \"y coordinate\")
+ (z \"z coordinate\")
+ :type real :initform 0)
+
+Which would have expanded the same way, but with documentation on each
+slot definition.
+
 There are a few flag style slot definition arguments. Flags do not
 have an value after them, all flags must come before other options. Flags are:
   :prefix - prefix the accessor by the class name
@@ -81,11 +92,23 @@ E.g.
                                               (write-only? :writer)
                                               (t :accessor))
                  :for slot :in slot-names
-                 :collect `(,slot
-                            ,accessor-type ,(make-accessor-name slot prefix-accessor?)
-                            ,@(unless no-arg?
-                                (list :initarg (alexandria:make-keyword slot)))
-                            ,@kwargs))))))
+                 :if (listp slot)
+                   :collect
+                   (destructuring-bind (slot doc) slot
+                     (check-type doc string "a string")
+                     `(,slot
+                       ,accessor-type ,(make-accessor-name slot prefix-accessor?)
+                       ,@(unless no-arg?
+                           (list :initarg (alexandria:make-keyword slot)))
+                       ,@kwargs
+                       :documentation ,doc))
+                 :else 
+                   :collect
+                 `(,slot
+                   ,accessor-type ,(make-accessor-name slot prefix-accessor?)
+                   ,@(unless no-arg?
+                       (list :initarg (alexandria:make-keyword slot)))
+                   ,@kwargs))))))
 
        (parse-class-options (kwargs)
          (loop :for (key val . more) :on kwargs :by #'cddr
@@ -148,4 +171,3 @@ E.g.
                   (optimize (speed 3) (safety 0)))
          ,@(if docstring (rest body) body)))))
 
-
-- 
cgit v1.2.3