# Second set of comments on chapter 2

These comments cover defgeneric (slightly revised from what I mailed
out earlier) through remove-method.

2-24 fourth paragraph: The calls to fboundp and symbol-function are
missing quote marks.  In the second sentence, new-value should be in
italics, not bold.  Can this be rephrased to avoid introducing the term
"setf generic function"?  Perhaps this paragraph could be merged into
the second paragraph, simply saying that -name- can be a symbol or
a setf-list.  Then the fboundp/symbol-function rules wouldn't have to
be stated twice.

2-24 I'm not sure I understood the double square bracket notation used
in this chapter, but it appears to be saying that defgeneric is only
allowed one option.  Maybe this is just a typo of a missing asterisk?
But maybe the syntax could be simplified by making -method-description-
a subcase  of -option-.  I'm not sure that -method-specifier- needs to
be a separate syntatic nonterminal symbol; why not merge this into
-method-description-?
2-44, 2-46, 2-48, 2-77: ditto

2-24 I'd prefer not to have separate syntax for lambda-list and setf-lambda-list,
since this requires the reader to study them to figure out what is different.
It would be better to use one syntax and say in text that the new-value is
the first required argument (and therefore there must be at least one required
parameter).  Affects 2-26 fifth paragraph, 2-28 fourth paragraph too.
2-44, 2-48, 2-77: ditto

2-24 I'm not sure we want to allow the (var) form for an optional parameter
specifier in defgeneric.  The 87-002 document was ambiguous here, but I had
read it as allowing only a symbol as an optional parameter specifier, so I
was surprised to see that the other form was being allowed now too.  Similarly
for keyword parameter specifiers, I would allow var and ((keyword var)), but
would forbid (var).  The (var) forms seem to me likely to mislead someone
into thinking that default value forms are permitted here.  I admit this is
a matter of taste.
2-44, 2-48, 2-77: ditto

2-25 last line: (eql -object-) should be (eql -form-) since -form- is
a form that gets evaluated at the time the defgeneric is evaluated, and
the value of -form- is the object that an argument has to be eql to to
satisfy the parameter specializer.  Appears again on 2-27 fifth bullet.

2-26 discussion of optimize declaration: change "defmethod form" to
"defmethod form or method-description".

2-27 "specialized-setf-lambda-list" is mentioned here, but is not in the syntax.
It can be removed.

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

2-30 end of third bullet: "but this is not required" should perhaps be
"this is the default, but is not required", since -operator- defaults to -name-.

2-30 third paragraph from bottom of page last sentence: "define by the
define-method-combination macro", insert "the short form of".

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

2-36 last Purpose paragraph: I don't think we need the concept of "setf
generic function", so I'd like to see this paragraph go away.
2-37 second paragraph: ditto.

2-36 last line: (eql -object-) should be (eql -form-).  Also maybe
-symbol- should be -class-name- for increased clarity.
2-37 fourth paragraph: ditto.  Here we need to explain about -object-
being the value of -form-, as on 1-23.

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

2-40 Add missing bullets: "The form (documentation -symbol- 'variable)
returns the documentation string of the special variable or constant
named by the symbol.  The form (documentation -symbol- 'structure)
returns the documentation string of the {\bf defstruct} structure named
by the symbol."

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

2-42 second Purpose paragraph: This is wrong, isn't it?  Shouldn't it
say the same thing as defgeneric says, namely if (fboundp -name-) is
nil, a new generic function is created and stored there, otherwise
if (symbol-function -name-) is not a generic function, signal an error.

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

2-42 first Arguments paragraph second sentence: I think we can delete
this sentence, the concept of setf generic functions isn't useful.

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

2-54 syntax: delete the italicized word "initargs".  The make-instance
generic function doesn't have any keyword parameters of its own.  In
the second arguments paragraph, change "The -initargs- argument is" to
"The remaining arguments are".

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

2-54 first remarks paragraph: I think this is misleading.  Instantiating
a standard type class has to be "may be extended" rather than "signals
an error", since in a given implementation a standard type class can
be implemented as a standard class.  The paragraph as written is not
actually wrong, because it carefully refers to what the metaclass actually
is rather than whether the class is documented as a standard type class.
However, I think there is plenty of scope for confusion here and the
wording should be clarified somehow.

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

2-56: I don't like the use of -old-class- as the name of the argument to
make-instances-obsolete.  There isn't anything old about the class object,
it remains in effect.  I'd rather it was just named -class-.

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

2-57 add to Arguments section:  If -method-list- is nil and :operator is
:call-next-method, the result is nil.

2-57 last paragraph: Delete.

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

2-60: I think method-qualifiers belongs in chapter 3.  I know it's
referenced on page 2-32, I still think it belongs in chapter 3.

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

OPEN ISSUES:

2-37 second Remarks paragraph: We need to decide whether defmethod
creates a new method object or modifies the existing one, and say
explicitly which it is.  I prefer modifying the existing one, and
the way add-method is described suggests to me that this is what is
intended, but I think Gregor disagrees.

2-55: I suspect more initargs are needed when creating an instance
of standard-method.  Certainly something has to be done to make the
method's keyword parameter keyword names available, because of the
way keyword arguments to generic functions now work.  Do the metafolks
have a suggestion here?

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

TYPOS:

2-28 second Remarks paragraph: "a anonymous"

2-34 line 6: "(progn" should be indented.  The two make-method-call
forms that are inside the progn should be indented another space or
two to make the nesting structure more obvious.

2-23 In the first "define-method-combination and", delete "()" from
the methods clause, so unqualified methods will not be accepted.

2-42 third Purpose paragraph: "that has different value", add "a".

2-42 fourth Purpose paragraph: "and there are no methods" should
be "or there are no methods".

2-61 purpose: "next-method-s" should be "next-method-p".

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