X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/dea4d05507e59ab779ed4bb209e05971d87e260c..097d5a3ebbadefec2471e0046ab62a312b459934:/src/classes.lisp

diff --git a/src/classes.lisp b/src/classes.lisp
index 3d01f57..a670b8e 100644
--- a/src/classes.lisp
+++ b/src/classes.lisp
@@ -25,6 +25,21 @@
 
 (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.
 
@@ -182,16 +197,16 @@
    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)
@@ -326,7 +341,7 @@
    (class :initarg :class :type sod-class :reader sod-message-class)
    (type :initarg :type :type c-function-type :reader sod-message-type))
   (:documentation
-   "Messages the means for stimulating an object to behave.
+   "Messages are the means for stimulating an object to behave.
 
    SOD is a single-dispatch object system, like Smalltalk, C++, Python and so
    on, but unlike CLOS and Dylan.  Behaviour is invoked by `sending messages'
@@ -409,27 +424,27 @@
        will, in general, differ from the type of the message for several
        reasons.
 
-	 -- Firstly, the method type must include names for all of the
-            method's parameters.  The message definition can omit the
-            parameter names (in the same way as a function declaration can).
-            Formally, the message definition can contain abstract
-            declarators, whereas method definitions must not.
+	 -- The method type must include names for all of the method's
+	    parameters.  The message definition can omit the parameter
+	    names (in the same way as a function declaration can).  Formally,
+	    the message definition can contain abstract declarators, whereas
+	    method definitions must not.
 
 	 -- Method combinations may require different parameter or return
-            types.  For example, `before' and `after' methods don't
-            contribute to the message's return value, so they must be defined
-            as returning `void'.
+	    types.  For example, `before' and `after' methods don't
+	    contribute to the message's return value, so they must be defined
+	    as returning `void'.
 
 	 -- Method combinations may permit methods whose parameter and/or
-            return types don't exactly match the corresponding types of the
-            message.  For example, one might have methods with covariant
-            return types and contravariant parameter types.  (This sounds
-            nice, but it doesn't actually seem like such a clever idea when
-            you consider that the co-/contravariance must hold among all the
-            applicable methods ordered according to the class precedence
-            list.  As a result, a user might have to work hard to build
-            subclasses whose CPLs match the restrictions implied by the
-            method types.)
+	    return types don't exactly match the corresponding types of the
+	    message.  For example, one might have methods with covariant
+	    return types and contravariant parameter types.  (This sounds
+	    nice, but it doesn't actually seem like such a clever idea when
+	    you consider that the co-/contravariance must hold among all the
+	    applicable methods ordered according to the class precedence
+	    list.  As a result, a user might have to work hard to build
+	    subclasses whose CPLs match the restrictions implied by the
+	    method types.)
 
    Method objects are fairly passive in the SOD translator.  However,
    subclasses of `sod-message' may (and probably will) construct instances of