Comments on (the skeleton of) Chapter 3

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

This is my final set of initial comments on this draft of the document.
Soon, probably later today, I will send out comments based on checking
the document against my list of decisions that I think we have reached.


3-5 says the value of CHECK-INITARGS is an initialization argument list,
but 1-39 says the value is ignored.  I prefer 1-39.

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

3-6, 3-9 Purpose: We have a problem with class-direct-initargs for
method-implemented initargs defined by allocate-instance methods on
individuals.  This is because methods on individuals don't conform to
the usual rule of thumb that the applicable methods for a class are the
union of the applicable methods for it and its superclasses.

After some thought, I think the right approach is to leave
class-direct-initargs the way it is, but change class-all-initargs not
to be defined in terms of class-direct-initargs.  Instead
class-all-initargs should be defined in terms of the union of two sets:
  - the result of mapping car over class-all-slot-initargs (which in
    turn is defined in terms of class-direct-slot-initargs of the class
    and its superclasses)
  - the union of the mapping of method-keyword-names over the result of
    compute-applicable-methods.

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

3-7 Purpose: I think we should say explicitly why both the function and
the form are present.  The form is only there for documentation; it is not
legitimate to try to evaluate it, since you don't have the accompanying
lexical environment.  The function is there to be called.  I suppose it's
not really necessary to say that the function's body might not really be
the default value form, for instance the function might be a closure of
a predefined function with the default value form in its environment, in
some cases.

3-10 Purpose: ditto

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

3-12 Values: I think the same disclaimer about modifying the returned value
used by class-all-initargs and so forth should appear here.  See typos
in that disclaimer noted below.

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

3-16, 3-17, 3-18: I think the same remark about why the -class- argument
is present should appear here as appears at the bottom of page 2-69.
Also we ought to say explicitly that these functions exist to be called
by the chapter 2 functions of similar names (except when they get
optimized out at compile time).

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

OPEN ISSUES:

3-14:  I think Gregor wanted to do finalize-inheritance differently, so I
won't try to do a full rewrite on this now, I'll just respond to the questions
in brackets.  This should make the writeup a little better, although it still
won't be up to the standard of the earlier portions of the document.

I don't know a much more precise definition of "when anything relevant changes."
I guess this gets called whenever the slots, slot descriptions, default initargs,
or direct superclasses of the class or any of its superclasses is changed,
and finalize-inheritance has already been called at least once for the class.
In addition, it gets called when a method is added, removed, or has its
keyword argument names changed.  I'm not sure whether this applies to methods
for all generic functions, or just for the initialization generic functions.
Maybe that's up to each generic function to decide?  Right now in Flavors,
something analogous is called whenever the class or any of its superclasses
is redefined in any way, or if an initialization method is defined, redefined,
or undefined.  We don't actually bother with the optimization of trying to
detect redefinitions that don't actually change anything.

Also perhaps it wasn't clear that this function is called by the system,
not intended to be called by the user, and is intended to have methods
written by the user.

Last purpose paragraph should be: The system-supplied methods for
finalize-inheritance conspire with the system-supplied methods for
make-instance, default-initargs, check-initargs, allocate-instance, and
initialize-instance to speed up object creation by precomputing some
information and storing it in slots of the class.  This optimization
is implementation-dependent, but the finalize-inheritance mechanism that
makes such optimizations possible is standardized.

The -class- argument is a class, not a class name.

The returned value is ignored.

The Remarks field seems okay as it stands.  We can't be more specific about
"things" because these are determined by the user's special optimization needs,
not something we know in advance.

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

TYPOS:

3-4 Remarks: "customize the behavior allocate-instance", add "of"
3-5: ditto

3-6 Purpose: "given calss"

3-6 Arguments: "argument" should not be in italics.

3-6 Values: "including the name", add "s".

3-6 Remarks: "undefined if the values returned by this function are modified",
I think should be "undefined if the value returned by this function is modified".
Second remarks sentence ditto.  Also I think the two sentences should be in a
single paragraph.
3-7, 3-8, 3-9, 3-10, 3-11 Remarks: ditto

3-8 Purpose line 3: "followed by the name of all slots", "name" -> "names"
3-11 ditto

3-9 Purpose line 4: "that defined" -> "that were defined"

3-13 Purpose line 1: ":default-initarg", add "s"

3-13 Remarks line 1: "customize the behavior default-initargs", add "of"

3-14 Arguments line 2: "whenthe"

3-15 Purpose lines 1,2: "keywords names" -> "keyword names"

3-15 Purpose line 2: "specificers"

3-15 Purpose line 3: "instand"

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