Comments on latest draft documents

[David A. Moon <Moon@STONY-BROOK.SCRC.Symbolics.COM>]

Jan 20, 1988 20:06 draft of chapter 1:

1-15: The first paragraph under "Initializng Newly-added Shared Slots" needs
to clarify that if there is no :initform, the shared slot remains unbound.
The remaining two paragraphs under that heading belong under the next heading.

1-17: The first bullet under "Extensions" refers to the new class being an
instance of the old class, which doesn't make sense.  I think it meant to
say "the old metaclass."

1-27: The list of method-defining forms should include defclass (because
of the :reader, :writer, and :accessor slot-options).

1-28 first non-bullet paragraph: The reference to method defining forms
that create generic functions really only applies to those method defining
forms that are not also generic function defining forms.  Perhaps you need
a term for these.  They are defmethod and defclass.

1-28 last bullet: In the reference to "The form (eql form)", the first
use of the word "form" is incorrect, since this is not technically a form.
I'd prefer either "The list (eql form)" or "The parameter specializer name
(eql form)".

1-29 paragraph numbered "2": P sub 1,i is a parameter specializer, not a
parameter specializer name; in the same sentence, the word "denote" should
be "are", for the same reason.

1-30 first line: This incorrectly assumes qualifiers have to be symbols.
Elsewhere we have indicated that qualifiers are compared with EQUAL.
Thus this line should be changed to "3. The lists of qualifiers of both
methods are {\bf equal}."

1-30 after rule 6: The reference to method-defining forms creating generic
functions applies only to the ones that are not also generic function
defining forms.

1-37: The list of names of built-in method combination types should include
STANDARD, or else the text should say this is the list of the m-c types
described just above, rather than all of them.  Probably the former is
better, since the next sentence mentions the semantics of STANDARD m-c.

1-37 last bullet second sentence: "applicable methods" should be
"applicable primary methods".

1-40 first bullet: I assume generic functions created by defclass
also have class standard-generic-function, so add defclass to this list.

1-43 third paragraph third sentence: Add "and is not defaulted by a more
specific class."  At most one default initial value form will be evaluated
for a given initialization argument, the form supplied by the most specific
of the classes that supply them.

1-44 fourth bullet second sentence: I fin the phrase "and the values of
the remaining default value forms are ignored" to be misleading.  I think
it would be better just to delete it.  Otherwise the conflict of number (the
earlier portion of the sentence indicated just two default value forms were
being discussed) and the risk of the reader misinterpreting this to say that
the other default value form is not evaluated would have to be dealt with.

1-45 fourth bullet third sentence: "less specific primary method" is a
typo for "more specific primary method".

Jan 21, 1988 17:39 draft of Chapter 2:

2-17 class-name: The name of a class should not be restricted in type.  The
method signature should specialize new-value with t, the arguments should
say new-value is typically a symbol, and the semicolon clause under
values should be deleted.  While a class's proper name is a symbol
unless symbol-class is somehow extended, class-name should be allowed
to be any object.  One proposed extension we discussed earlier has
class-name a list of classes.

2-18 class-of remarks: If we're going to cross-reference figure 1-1, we
have to point out that class-of does not necessarily return the classes
listed there.  It could return an implementation-dependent subclass.
However, we are adding a restriction beyond Common Lisp's TYPE-OF, because
for members of the classes in 1-1, it is not permitted for CLASS-OF to
return a superclass of the class listed.  It might be worth pointing that
out explicitly here; to deduce this from what is already documented the
reader would need to know that generic function to method dispatching calls
CLASS-OF.

2-41 documentation method signatures: The parameter specializer name
for new-value should be t, not string.  CLtL doesn't say anywhere what
values are allowed, but a reasonable inference is that NIL is allowed,
and "documentation information" might have been meant to include some
sort of structures as well.  The allowable types here are a matter for
CL to define, not for CLOS to legislate.

2-52 initialize-instance method signature: &key &allow-other-keys can't be
right for the method; this would prevent check-initargs from doing
anything.  It should be &rest initargs.  Note that &key &allow-other-keys
-is- correct for the generic function (the syntax field).

2-81 with-added-methods remarks: The second paragraph and the two bullets
that follow it are slightly garbled.  I believe this means to say what
happens when with-added-methods does -not- specify an option (the value
in the existing generic function is retained, rather than defaulting to
the default that efgeneric would use), however it doesn't say that.  What
it does say doesn't really make sense, because it speaks of option
inheritance and then says how the options of the existing generic function
are all replaced.

That's it for now, but a small number of additional comments will follow,
tomorrow.