Comments on Chapter 1

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

Comments on the draft of chapter 1 dated Dec 23, 1987 13:37.  This is
probably my last round of comments for chapter 1.

1-10 and several others: I'm not sure that the introduction of the new term
"captured :initform form" really adds anything to understandability.  It ends
up that "captured" is the only kind there is.

1-11 3rd paragraph last sentence: "Accessors are implemented using readers and
writers, and readers, writers, and accessors are implemented using {\bf
slot-value}."  If there is such a thing as an accessor, it is either a reader
or writer, it isn't implemented using readers or writers.  I'd rather see
"Reader and writer methods are implemented using {\bf slot-value}."

1-11 4th paragraph: several editing errors in switching between writer and
accessor here.  I suggest "When a reader or writer is specified for a slot,
the name of the generic function to which the generated method belongs is
directly specified.  If the name specified for the accessor option is the
symbol {\it name}, then the name of the generic function for reading the slot
is the symbol {\it name\/} and the name of the generic function for writing
the slot is the list {\tt (setf {\it name\/})}."  Also the last sentence, "It
is possible to modify the behavior of these generic functions by writing
methods for them.", seems like a non-sequitur.  The point this is trying to
make is that you can write methods explicitly with defmethod, as well as
writing methods implicitly with the slot options, and you can mix both kinds
of methods on the same generic function.  Perhaps the sentence should be in
its own paragraph and should be rephrased slightly.

1-11 last paragraph: This is a good place to mention with-accessors,
assuming that we are adding it.

1-12: The second paragraph under "Inheritance of Slots and Slot Options"
no longer says what happens if the :allocation slot option is omitted.
It used to.  Delaying that until later seems confusing to me.

1-13: "Reader and accessor methods are inherited in the sense described in
the section ``Inheritance of Methods.''" should say "writer" rather than
"accessor" now.

1-13 last paragraph: "If a given {\bf :default-initargs} class option
specifies an initialization argument of the same name more than once, the
leftmost supplies the value and the remaining occurrences are ignored."
I don't think this is right; it should be an error to specify the same
initialization argument name more than once in a single :default-initargs
class option.

1-14 last sentence: "there is also a method for {\tt setf} of {\tt S3} that
writes the value of {\tt S3}."  This is wrong, it's a method for {\tt setf} of
{\tt C2-S3}.  Perhaps the first half of the sentence should mention explicitly
that the reader method is on the generic function named C2-S3.

1-15 last paragraph in first section: In "discarding local slots that are not
defined in the new version of the instance", the last word is probably
supposed to be "class", not "instance", since "defined" refers to classes.
Alternatively, perhaps the word "defined" was supposed to be "accessible".
Also "and initializing newly-added shared slots" can't be part of the two-step
process of updating an instance.  This phrase belongs two paragraphs earlier,
where we are discussing shared slots.

1-15 first paragraph in second section: "defined by old class" is missing
"the".  Also this whole paragraph bothers me because it uses "defined" and
"specified" interchangeably, or else there is a subtle difference between the
two words that I haven't grasped.  Earlier (1-12) "defined" meant only local
definitions of slots, as opposed to inherited ones, so a different word should
be used.  "Accessible" if it fits, otherwise "specified" I guess.

1-16 first paragraph: "declass" should be "defclass".  The meta object folks
could rightly point out that there is too much emphasis on defclass forms
here, that there are other ways to define classes, and that we could be
clearer about the distinction between the name layer and the object layer.
However, perhaps being pedantic about that would just make the writeup harder
to read for no real benefit.

With the above corrections I think the new description of class redefinition
is a definite improvement.

1-17: same specified/defined wording issue.

1-19 first sentence: Isn't the mapping from classes into types, rather than
the inverse as it says here?  Not all types are mapped to a class.

1-20 in the table: "sequnce" should be "sequence".

1-20 bottom: The incomprehensible sentence "However, individual
implementations are not free to add subclass relationships involving
user-defined standard classes." was removed.  I think what this meant to say
is that a standard class defined with no direct superclasses is guaranteed to
be disjoint with all of the classes in the table, except for t.  That probably
needs to be said.  Note: my little phrase "with no direct superclasses" there
seems like the cleanest way to rule out the loophole of the user explicitly
defining a subclass of one of the potentially built-in classes that doesn't
happen to be built-in.

1-20: Do we want to say in this document that we plan to add the following
types/classes to the table whenever Common Lisp is fixed to define their
relations to other types properly?  It seems like that intention ought to
be documented someplace.
  function  hash-table  package  pathname  random-state  readtable  stream

1-23 second paragraph: "The class {\tt apple} is a direct subclass of {\tt
fruit} and is rightmost in the precedence list." leads to an unfortunate
ambiguity where a reader might think that the direct subclass has to be the
very last element of the precedence list computed so far.  A better way to say
it that avoids this ambiguity would be "The class {\tt apple} is a direct
subclass of {\tt fruit} and the class {\tt pie} is a direct subclass of
{\tt cinnamon}.  Since {\tt apple} appears to the right of {\tt pie}
in the precedence list, {\tt fruit} goes next ..."

1-24 with-added-methods paragraph: In "If there is a lexically visible
ordinary function of the same name as one of the method definitions, that
function becomes the method function of the default method for the new generic
function of that name.", "as one of the method definitions" should be deleted,
or replaced by "as the specified generic function name."

1-27 rule 4: This could be misinterpreted as implying that if a method has
an &rest parameter, the value of that parameter will include the symbols
:allow-other-keys and t even if the arguments supplied by the caller of the
generic function did not include those symbols.  We should say explicitly
that that is not the case; a method's &rest parameter will see only the
actual arguments.  I think it would be clearer to go back to saying that
a method function receives keyword arguments in the same way that it would
if the method lambda-list had included &allow-other-keys.

1-31 second to last paragraph: "A method for {\bf compute-effective-method}
can be defined directly by using {\bf defmethod} or any of the other
method-defining forms..." is not really true.  The other method-defining forms
can define a method for a generic function named compute-effective-method,
but it won't actually be the same generic function that the method combination
mechanism calls; that mechanism calls the generic function that has that name
globally, not any generic function that has that name lexically.  I'd
let this refer only to defmethod and define-method-combination.

1-32 first paragraph: A period is missing in "procedure Some illustrative
examples".

1-34 first bullet: "those those"

1-34: How come "An error is signaled if {\bf call-next-method} is used in a
{\bf :before} or {\bf :after} method." was removed?  I think we need to make
it clear that call-next-method isn't allowed in before and after methods.

1-34 last paragraph of first section: "shadowed" should be "shadow".

1-37 first bullet: I think "method-defining forms" here is a typo for
something else.

1-40 last paragraph of first section: "The \OS\ does not guarantee any given
order of evaluation of default value and {\bf :initform} forms." is ambiguous.
This could be interpreted as saying that CLOS doesn't guarantee that all the
default value forms are evaluated before any of the :initform forms.  But I
think it does guarantee that.  What we really mean to say here is that CLOS
doesn't guarantee which of two default value forms is evaluated first, and
furthermore CLOS doesn't guarantee which of two :initform forms is evaluated
first.  Perhaps it could be better said as two sentences.

1-41 fourth bullet: "If a given {\bf :default-initargs} class option specifies
an initialization argument of the same name more than once, the leftmost
supplies the value and the remaining occurrences are ignored." should be
deleted and replaced by: "If a given {\bf :default-initargs} class option
specifies two initialization arguments that initialize the same slot, the
leftmost supplies the value and the values of the remaining default value
forms are ignored."