First round of comments on the draft document

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

Comments on the 20 Oct 1987 16:34 draft of the CLOS documentation
pages 1-1 through 1-32.

I don't think we need the concept of "setf generic function" at all
any more.  Such generic functions are now completely the same as
ordinary generic functions except that you get to them through
SYMBOL-FUNCTION of a name that is a list.  I don't think we need
special mention of "setf generic functions" all over the place.
I would just say in the paragraph on 1-21 that begins "In Common
Lisp, a name can be given to a function...", something like
the following: "The name of a generic function, like the name of
an ordinary function, can be either a symbol or a two-element
list whose first element is {\bf setf} and whose second element
is a symbol.  This is true for both local and global names."

The section "Introduction to Setf Generic Functions" can be completely
eliminated.  If we want to publicize the recent cleanup that introduced
setf functions, we can attach that as an appendix; in any case, I think
this is better explained without reference to generic functions.

1-8 bottom of page: change two references to "setf method" to
"a method for writing the value of the slot", and then after
"appropriate generic functions" say the reading generic function
has a name specified in the defclass, while the writing generic
function is named (setf -reader-).

1-25 second paragraph: We don't need to make any distinction about
setf generic functions here; delete the paragraph.

================

The section title "Changing Classes" is poor.  We aren't doing
anything to a class, we're doing something to an instance.  A
more appropriate title would be "Changing the Class of an Instance".

================

We need to put in the glossary.

================

1-3 sixth paragraph: "ordered set" should be "list" in two places,
to avoid implying that duplicates are eliminated from the "set" of
parameter specializers or the "set" of qualifiers.

1-23 first paragraph under Introduction to Methods: same comment.

================

1-6 fourth paragraph: Clarify the range of n in the definition of
"superclass".  I think you mean n >= 2, so that any "direct superclass"
is also a "superclass", but a class is not a superclass of itself.

================

1-8 bottom of page: "When a reader or accessor is specified for an
individual slot...": I don't understand what "individual" is in contrast to.
Every reader or accessor is for one slot, we don't have anything that
reads several slots and returns multiple values or anything like that.
If this sentence is just left over from the removal of :accessor-prefix,
we can just delete the sentence.

================

1-11 third bullet: we could just say "... union of the initialization
arguments declared in :initarg slot options in all the slot specifiers."
since all these bullets assume a set of slot specifiers for one name.

================

1-11 last sentence: needs to be updated with a correction I sent earlier,
because :default-initargs can appear more than once in a defclass.

================

1-15 last paragraph: It might be worth mentioning that the copy has dynamic
extent.  This is mentioned in the remarks on 2-13, but it might be worth
repeating here.

================

1-16 fourth paragraph last sentence: "It is not allowed" is not defined
in the error terminology section.  I think you mean "CLOS may be
extended to cover make-instance of a standard-type class or inclusion of
a standard type class as a superclass of a class."

================

1-18 last sentence: Actually a loop can contain more than two classes.

================

1-19 third paragraph last sentence: "will be followed by all classes
in T1", append "except t".  The example could actually be generalized
to a join class J that isn't t, provided none of J's superclasses
appear elsewhere in the graph than above J.  Then we have T1 up to
but not including J, followed by T2, ending in J and its superclasses.

================

1-23 last bullet: "(EQL -object-)" should be "(EQL -form-)", because
in a parameter specializer name, we have a form that is to be evaluated
to produce the object that appears in the parameter specializer.  The
paragraph immediately following is wrong where it says "otherwise N
equals P" for this reason.  We changed this when we changed QUOTE to EQL.

1-23 fourth paragraph: We no longer require parameter specializer names
to be Common Lisp type specifiers.  (EQL -form-) is not a type-specifier.

================

1-23 last paragraph: I think the reference to make-instance here should
be changed to say specifically "make-instance of standard-method".

================

1-24 last paragraph: It's no longer true in the short form of
define-method-combination that primary methods can be unqualified.
Now, primary methods are qualified with the name of the type of
method combination, while auxiliary methods are qualified with :around.

================

1-32 first sentence: generic-flet, generic-labels, and with-added-methods
also accept a :method-combination argument.

================

1-32 first bullet last sentence: I don't understand why the word "only"
is present here.  Maybe you mean "is supported only in :around methods
when a built-in" rather than "is supported in :around methods only when
a built-in"; i.e. does "only" modify ":around methods" or does it modify
"when"?  Also, this sentence should probably be pulled out of the bullet
since I think it is saying something about both method roles.  Maybe the
sentence should be deleted since the same information is repeated later
on the page.

================

OPEN ISSUES:

1-13 fourth paragraph: I think slot reinitialization should not be done
by a method for update-instance-structure.  Instead it should be done at
the meta-object level, and defined to be completed before
update-instance-structure is called.  This would be consistent with
change-class.

1-16 second paragraph: The specification about type-of here only applies
to instances of standard classes, or something like that.  It certainly
doesn't apply to instances of all standard type classes.  (Boy the
distinction between "standard class" and "standard type class" is
confusing!  The two names always sound the same to me.)

1-17 I still think it's wrong for list to be more specific than symbol
in the CPL of null.  Consider the print-object methods.  Also consider
the introjection of symbol between list and sequence, a surprising CPL.

================

TYPOS:

1-7 bottom of page: "the generic function uninitialized-slot" should be
"the generic function slot-unbound".

1-9 last sentence: "invokes the function slot-value is to", "is" is
a typo.

1-15 third sentence: "When an instance is updated", "updated" should be
"changed".

1-15 fifth paragraph: Delete the whole paragraph, this was accidentally
copied from the "redefining classes" section.

1-19: "(food t)" should be "(food, t)" in two places.  1-20 also.

1-22 third paragraph: "defintions"

1-22: "a names of the form (setf name)"

1-22: "Consider setf form (setf ..." should be "Consider the form (setf ...".

1-23 first line: We haven't defined the term "setf macro".  Could say
"a setf macro defined for name with defsetf or define-setf-method".

1-23 in the funcall: "#:temp-2" should be "#:temp-1".

1-25 bullet 4 last sentence: "in in" should be "in".

1-25 Section "Named Arguments...": In this section's title and text,
"named argument" should be "keyword argument".  My fault: I forgot to
mail out a corrected version of this section when the terminology
was changed back.