Comment on the chapter 2, Version of Nov 2.

[Danny Bobrow <Bobrow.pa@Xerox.COM>]

General Comment:  Much improved again.  Having method signatures makes a
big difference.  I think that if there is a method signature, there
should not be a section called Syntax.  They are to some extent
redundant, and where they are not, Syntax was almost always wrong.

2-8 This is the first example of the redundancy.  Please take out
Syntax, and the first two sentences under Arguments.  The signature
specifies what the types of the arguments must be, and if people add
another method the arguments need not be those objects.

For example, suppose someone wanted to add a method:
   add-method (s symbol) (lambda-exp listp)
where s was supposed to name a generic function and lambda-exp was a
list for a function, then the statements under arguments would be
untrue.

2-9 Last sentence of third paragraph  "It defines the next method ... "
--> "The standard method combination type defines the next method ... "
(I garden pathed on the "It")

2-11 The environment argument is only mentioned.  There is no statement
here, or later for symbol-class, etc about what it means to have the
environment. So for example, 
"(cboundp 'foo e1) returns true if foo is bound to a class IN THE
ENVIRONMENT DENOTED BY e1."

2-12 Second paragraph, first sentence should read
"If in the old class there is ANY slot of the same name as any LOCAL
slot in the new class, the value of that slot is unchanged"

Remove Syntax section,  Remove first two lines of Arguments.  The last
sentence should read
"... and then invokes the first method with the class returned as value
from (symbol-class symbol)."

In Remarks section, you can put the comment (if you want) about possible
extensions to objects that are not standard class. But I would just
leave it out as redundant with the introductory statement about
generic-functions being extendable.

Examples: you need an :initarg :x and :initarg :y in the defclass to
have the make-instance work on the next page.
  
2-13 Remarks: Second sentence "... can be used to assign values to slots
in the transformed instance."

Next paragraph:  Third sentence might read better as
  "The methods currently executing may no longer be applicable."  
The complication of combined methods is not worth the confusion here, I
think.

2-17 Purpose: Try "... and returns a symbol.  This symbol is not
guaranteed to be the name of this class.  See remarks below."

Remove Syntax.

Remarks:  It is possible that C /= (symbol-class(class-name C)).  For
example:

(defclass foo () (a))
(defclass bar () (b))
(setq f1 (symbol-class foo))
(setq f2 (symbol-class bar))
(setf (symbol-class foo) f2)
(class-name f1) --> foo
(class-name (symbol-class 'foo)) --> bar

2-19 Purpose: "... name a class IN AN ENVIRONMENT".

Remarks: It sounds like the symbol is somehow spoiled (" the symbol is
no longer usable as the name of a type").  Why not say something like
"the symbol is no longer associated with a class that defines a type."

2-21  syntax
replace {slot-option}* by [[â?? slot-option]]

and use
{:accessor generic-function-name}*
{:reader generic-function-name}* 
{:initarg name}*

as the last three items of slot-option.  Then the remarks on which
options can appear more than once in Arguments are redundant.

2-22 First paragraph.  "... the definition of that class is replaced FOR
INSTANCES OF STANDARD-CLASS."

2-23 para 2 "... is not allowed as an abbreviation for the syntax
(slotname :initform).  THIS IS DIFFERENT THAN DEFSTRUCT."

2-24 First sentence, same as for p 2-22 " ... class is guaranteeed to be
redefined for classes that are instances of standard-class."

2-26 
The syntax of defgeneric now shows a lambda-list as a required argument.
I thought :lambda-list was supposed to be a keyword argument.  Similarly
for generic-labels, generic-flet, generic-function, and
with-added-methods.  When there are method descriptions provided, the
lambda-list is often redundant, and hence can be a cause for mistakes.
My notes from the meeting show that there was no required lambda-list,
at least for the generic-labels, generic-flet, generic-function, and
with-added-methods.  Hence by extension, there should not be a required
lambda-list in defgeneric.

2-27  "The :argument-precedence-order option has a value which is a
permutation of the list of required arguments for generic function.  It
is used to specify the order in which the required arguments ...  When
the :argument-precedence-order is given, then an explicit lambda-list
for the generic function must be given. ..."

Example:
(defgeneric char-to-stream
  (:lambda-list (char stream &optional font))
  (:argument-precedence-order (stream char)))

Is this the correct syntax, or should it be:

(defgeneric char-to-stream
  (:lambda-list char stream &optional font)
  (:argument-precedence-order stream char))

I don't like this as well.


2-40
Remove Syntax for describe

2-41
Remove Syntax for documentation (Here it specifies that the second
argument is optional and we cannot specialize on optional arguments).
If Common Lisp has it as optional, then the signatures must only be on
the first type, with constraints specified in English on the optional
argument.
 
2-43

Purpose: Remove second sentence , that is "If name does not specify a
generic function, an error is signalled."

2-44 
"The keyword arguments correspond to the option arguments of defgeneric,
except that the :method-class and the :generic-function-class can be
class objects as well as names."

 2-45, 2-47, 2-49  Remark about required lambda-list again.

2-55 

This description of make-instance is just wrong.  The signatures are
wrong (they are off a metalevel). They would be appropriate signatures
for initialize-instance  It should say something like

Method Signatures:
  make-instance (class standard-class) &key &rest initargs

Arguments:
  The initargs arguments are explicitly checked within make-instance by
the generic function check-initargs.  These initargs are the union of
the keyword arguments allowed for all applicable methods on
initialize-instance, and the :initarg options of the class.  
See the section on Object Creation.  For instances of particular
classes, see the description of the initialize-instance method.

---
Then if we want we can put in the remarks section on initialize-instance
the arguments that each of the initialize-instance methods take.
[[However, I would prefer to see these in Chapter 3 under the
descriptions of the classes]]
 
initialize-instance  (class standard-class) &key :direct-superclasses
:direct-slots :options

The :direct-superclasses argument is a list of symbols (class names) or
class objects.  The :direct-slots argument is a list of slot-description
objects (see chapter 3) and the :options is a list of the type accepted
by defclass as class options, except :metaclass is not allowed.

initialize-instance (gfn standard-generic-function) &key :lambda-list
...

initialize-instance (method standard-method) &key  ...


 2-58 Purpose (Why is this one plural?)
"... when defclass has been used to redefine an existing class WITH
METACLASS standard-class."

Remove Syntax

Arguments:  The class argument is a class object whose instances are to
be made obsolete.

2-59
Next to last paragraph. "... the result is a form that calls the first
method, M1, and arranges for call-next-method to reach the next method,
M2, in the list.  An invocation of call-next-method in M2 reaches the
following method, M3, and this continues through the methods in the
order they appear in method-list.  If a call-next-method is invoked by
the last method in method-list, an error is signaled."

2-64

Remove Syntax.  Remove comment in purpose about method on
standard-generic-function signals an error (It appears 6 lines below)

2-67 Remove syntax.  Remove first two sentences of Arguments.

2-74
Again something needs to be said about relationship of name and
environment.

2-80
It needs to be said that if name is bound to a macro, then an error is
signalled.

2-82
There are quote marks that are missing around slot-entry in all calls to
slot-value.
e.g.   (slot-value #:Temp 'slot-entry1)