Update readme

1 files changed, 49 insertions, 6 deletions

diff --git a/README.md b/README.md
index 418f3da..d6010a2 100644
--- a/README.md
+++ b/README.md
@@ -5,8 +5,8 @@ A stupid project to dull the pain of using a few of CL's built-in `def*` forms.
 ## `def:var`
 
 Isn't it annoying that, if you want to leave a `defvar`-defined
-special variable uninitialized at the top-level, then you're not
-allowed to give that variable a docstring? 
+special variable uninitialized, then you're not allowed to give that
+variable a docstring?
 
 Sure, you can always 
 
@@ -59,13 +59,56 @@ The above would expand out into
       ((X :ACCESSOR PT-X :INITARG :X :TYPE REAL :INITFORM 0)
        (Y :ACCESSOR PT-Y :INITARG :Y :TYPE REAL :INITFORM 0)
        (Z :ACCESSOR PT-Z :INITARG :Z :TYPE REAL :INITFORM 0)
-       (UUID :READER UUID :INITARG :UUID :TYPE INTEGER :INITFORM
-             (MAKE-UUID) :DOCUMENTATION "A unique ID"))
+       (UUID :READER UUID :TYPE INTEGER :INITFORM (MAKE-UUID)
+             :DOCUMENTATION "A unique ID"))
       (:DOCUMENTATION "A point in real 3d space"))
       
-See `def:class`'s docstring for details.
 
-## `def:fast` 
+The syntax of the macro is:
+
+    (def:class class-name (supers ...) body-and-slots...)
+    
+The `CLASS-NAME` and `SUPERS` follow `DEFCLASS` syntax.
+
+Each member of `BODY-AND-SLOTS` is a slot definition list, a keyword
+naming a class option, or a value bound to a class option. 
+
+The class options are the same as those accepted by `DEFCLASS`, and
+**Any class options must follow ALL slot definitions!**  E.g. in the
+above `PT` example, the `:DOCUMENTATION` class option follows the two
+slot definition lists.
+
+Each slot definition is, in order:
+
+- One or more slot name (with optional docstring)
+- Zero or more slot flags
+- Zero or more slot options
+
+The following are all valid slot definitions:
+
+;; define three slots
+(x y z) 
+
+;; define three read-only slots initialized to zero whose readers are
+;; prefixed with the class name
+(x y z :prefix :ro :initform 0)
+
+;; define two string-valued required slots
+((first-name "First name") 
+ (last-name "Last name")
+ :ro :required 
+ :type string)
+
+The following flags are accepted:
+
+- `:prefix` prefix the accessor by the class name
+- `:ro` only define a reader 
+- `:wo` only define a writer 
+- `:noarg` means no initarg
+- `:required` the slot MUST have an initial value
+
+
+## `def:typed` 
 
 Common Lisp compilers like SBCL can produce extremely fast code
 ... if, that is, you help them out a little.