(cl:in-package #:sod)
+;;; Note! You'll notice that none of the classes defined here store property
+;;; sets persistently, even though there's a `:pset' keyword argument
+;;; accepted by many of the classes' initialization methods. That's because
+;;; part of the pset protocol involves checking that there are no unused
+;;; properties, and this typically happens shortly after the appropriate
+;;; objects are constructed. It would be tempting to stash the pset at
+;;; initialization time, and then pick some property from it out later -- but
+;;; that won't work in general because an error might have been signalled
+;;; about that property. It wouldn't surprise me greatly to discover that
+;;; `most' code paths resulted in the property being looked up in time to
+;;; avoid the unused-property error, but a subtle change in circumstances
+;;; then causes a thing done on demand to be done later, leading to
+;;; irritating and misleading errors being reported to the user. So please
+;;; don't do that.
+
;;;--------------------------------------------------------------------------
;;; Classes.
computed on demand via methods on `slot-unbound'.
* The ILAYOUT describes the layout for an instance of the class. It's
- quite complicated; see the documentation of the ILAYOUT class for
+ quite complicated; see the documentation of the `ilayout' class for
detais.
* The EFFECTIVE-METHODS are a list of effective methods, specialized for
the class.
* The VTABLES are a list of descriptions of vtables for the class. The
- individual elements are VTABLE objects, which are even more
- complicated than ILAYOUT structures. See the class documentation for
- details."))
+ individual elements are `vtable' objects, which are even more
+ complicated than `ilayout' structures. See the class documentation
+ for details."))
(defmethod print-object ((class sod-class) stream)
(maybe-print-unreadable-object (class stream :type t)