format for description of generic functions in chapter 2

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

    Date: 04 Nov 87  1018 PST
    From: Dick Gabriel <RPG@SAIL.Stanford.EDU>

    I propose, then, that the policy of CLOS be that purpose statements be promoted
    to apply to generic functions whenever feasible.

I agree with that.  However, the new.dvi file that is a sample of the
new format does not seem to be written that way.  Lengthy comments about
this below, but first a relatively minor comment on the format.

Too much of the text in a method signature is italicized.  Only the
parameter names should be italicized; the parentheses, lambda-list
keywords, and parameter specializer names should be in should be in a
roman font or a typewriter font; this would be more consistent with the
style used elsewhere.

    This brings up the second general point, which is are we going to require
    that a pristine CLOS have all and only the methods described in the
    specification? Danny's proposed rewrite of the description of CHANGE-CLASS
    implies he believes so. I tend to favor the restriction.

    Currently there is a statement in the introduction to Chapter 2 that
    states:

    ``Any implementation of the \CLOS\ is allowed to provide other methods
    for the generic functions described in this chapter.''

    Opinions?

I don't think we can reasonably restrict implementations from defining
other methods.  Such a restriction would be inutile in any case, since
CLOS programs are obviously allowed to define other methods, and we want
to allow multiple programs to coexist in the same Lisp.  Thus any program
that assumes that only the methods defined in this chapter exist is not
going to be a good citizen of the Lisp world.  However, what we can say
is something like only the standard methods will be applicable to standard
objects; I think that is not precisely what I mean, but something along
those lines; the intent is that you can add new methods to extend the
behavior of the functions, but you're not supposed to break the behavior
of existing methods.

    Date: Wed, 4 Nov 87 10:58 PST
    From: Gregor.pa@Xerox.COM

    For example,
    in print-object, an implementation should be free to have methods on as
    many of its pre-defined classes as it likes, but it should not be
    allowed to define print-object methods on user-defined classes behind
    said user's back.

Yes, that expresses it pretty well.

	Date: 04 Nov 87 10:18 PST
	From: Dick Gabriel <RPG@SAIL.Stanford.EDU>

	I propose, then, that the policy of CLOS be that purpose statements be promoted
	to apply to generic functions whenever feasible.

    Whenever 'reasonable' is more like it.  For example, the purpose of the
    add-method generic function is to add a method to a generic function.
    If there is already a similar method an error is signalled.  The generic
    function is completely updated to know about the new method.

    The particular method on (standard-gf standard-method), has some of its
    own private behavior as well.  For example, it defines what it means for
    methods to be similar in this case (same qualifiers and specializers).
    It also defines what the lambda-list congruence rules will be.

    So its not a matter of whenever feasible, its a matter of reasoning it
    out on a case by case basis.

I agree with this.  The new.dvi writeup for add-method isn't written this
way, though.  More about this below.

Actually, I disagree with one detail of what Gregor said.  I can't understand
why lambda-list congruence should be restricted to standard generic functions
and standard methods.  To me lambda-list congruence seems equally applicable
to all generic functions and methods, and furthermore it's hard to see how
generic functions could work or users could call them if there wasn't
lambda-list congruence.  Thus I think congruence is part of the contract of
add-method, and should not be demoted to association with a particular method.

    Date: Wed, 4 Nov 87 15:10 EST
    From: Sonya E. Keene <skeene@STONY-BROOK.SCRC.Symbolics.COM>

    I like the new method signatures.    They give good information in a
    concise format.  However, I don't believe that a Method Signature is 
    redundant with Syntax.

I agree.  I think the new.dvi format addresses this pretty well.

    We should be recommending that people learn 
    about the generic function first, and then (if necessary) learn about
    the individual methods.

I agree 100% and I think the new.dvi format is deficient in this respect.
More about this below.

    Date: 04 Nov 87  1532 PST
    From: Dick Gabriel <RPG@SAIL.Stanford.EDU>

    The general format is to start the page with a description of what
    the generic function syntax, the method signatures of all methods
    specified, the purpose of the generic function, its values, and
    remarks about it. The reader should be able to look at the top 4 inches
    of a function page and see the generic function lambda list and the
    method signatures.

    Then there is a line that separates the generic function material from
    the method descriptions. Each method description repeats the signature,
    adds any method-specific purpose, values, remarks etc.

This sounds very good to me, but the actual file doesn't seem to do it
precisely this way.  In particular, the values and remarks are
frequently associated with a particular method where they should be
associated with the generic function as a whole.  To me, values have the
same status as arguments, both are part of the interface that the
generic function contracts to supply, and which all methods must conform
to.  Sometimes there will be additional method-specific things to say
about arguments or values, and then the method can have one or both of
those fields, but the generic function should always have the arguments
and values fields, and I think the normal case will be that only the
generic function will have these fields.

Another problem is with ordering of fields.  In several cases, method
descriptions intervene between two parts of the generic function
description.  Often the remarks and the examples come after the methods.
I think this is wrong, especially in light of Sonya's last comment
above; I think the methods should always be at the end, with nothing
after them except the See also field.

Here are some comments on specific pages of the sample new format,
and then I'll address what I think is the general problem with this
new format.

add-method has too much in the method section and not enough in the
generic-function section.  In fact I don't think there is anything
to be said about the method specifically; everything that is there
now is the contract of the generic function as a whole, to which all
methods must conform.  Gregor disagrees with me about the congruence
part, but not the rest of it.

change-class: the second remarks paragraph is a remark about the
generic function as a whole, and has nothing to do with the specific
method to which it is attached.  The first remarks paragraph, in
contrast, applies just to this method, although I think it's
important for the generic function as a whole to undertake to call
class-changed; the only need for a method-specific remark about
class-changed is to document exactly when class-changed is called
by that particular method.  Maybe that detailed remark is unnecessary?

class-changed: I feel this page is an example of good organization, much
better than the other pages.  The division between generic-function and
method is exactly right.

class-name: I think the method signature is wrong; surely class-name
works on all classes, not just standard ones.  Surely
(class-name (class-of (cons 1 2))) returns something, even though
we don't guarantee that it returns the symbol CONS in all implementations
(it could be the name of an implementation-dependent subclass of CONS).

describe: again I think the method signatures are wrong.  What we require
is that there be an applicable method for every object that exists, not
that there be a method on the class T.  I complained about this before
when it was in English, I think, and I'm complaining about it again when
it's in method signatures.  This started as a typo and now is turning into
an explicit specification.  I also don't think we want to require that a
method exist for the exact class standard-object, although I feel less
strongly about that.  In the cases of describe and print-object, I think
no method signatures should be listed, and then we should say that the
implementation provides enough predefined methods to assure that there
is always an applicable method, but we do not standardize the precise
parameter specializers of these methods.  If we do anything else we
are dictating how the PRINT function is modularized, which is not our
business.

describe: the documentation of the methods here is useless.  I suggest
that the format should permit omission of documentation of methods when
the documentation wouldn't say anything.

Here's the big problem with this new breakout of methods and generic
functions:  We are uncovering a significant amount of confusion about
what is the contract of a generic function, versus what is a property
of particular methods for that generic function.  In effect all of
the issues and uncertainties surrounding meta-objects have suddenly
leaked into the part of the document that we thought was almost
finished.  I'm really opposed to that because I think it sets us back
a long way.  It's really not necessary to resolve all those issues
to get something that is entirely useful to someone who is just going
to call these generic functions and not define new methods for them.
On the other hand, I do think the introduction of the method signatures
was a good idea, and I think the format as described in the quotation
from RPG above is a good idea.  If we can keep the documentation in the
style of the sample class-changed writeup, I'll be happy with the new
format, but if we're going to get bogged down in all these modularity
issues, I want no part of it.