Update readme

2 files changed, 57 insertions, 13 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.  
diff --git a/def.lisp b/def.lisp
index 055a30b..6a2505c 100644
--- a/def.lisp
+++ b/def.lisp
@@ -54,12 +54,13 @@ above might have been written:
 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
-  :ro     - only define a reader 
-  :wo     - only define a writer 
-  :noarg  - means no initarg
+There are a few flag style slot options. 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
+  :ro       - only define a reader 
+  :wo       - only define a writer 
+  :noarg    - means no initarg
+  :required - the slot MUST have an initial value
 
 By default an accessor is defined.
 
@@ -140,7 +141,7 @@ E.g.
 
 (defmacro typed (name (&rest lambda-list) -> return-type &body body)
   "A typed function is one for which every parameter is typed, a return type is
-declared. DEF:FAST generates an optimized DEFUN.
+declared. DEF:TYPED generates an optimized DEFUN.
 
 Each positional parameter must be a list (VAR TYPE) &KEY &REST and
 &OPTIONAL arguments all look like (VAR TYPE . MORE) where MORE is