format for description of generic functions in chapter 2

[Gregor.PA@Xerox.COM, Bobrow.PA@Xerox.COM]

    Date: Wed, 4 Nov 87 20:38 EST
    From: David A. Moon <Moon@STONY-BROOK.SCRC.Symbolics.COM>

First off, we want to say that we think the new method signature stuff
is a good idea and looks good overall.

    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.

Right.

    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.

Right, this is hard to word, but we are going to have to make some stab
at it.  We will try to take a stab at this later.

	Date: Wed, 4 Nov 87 10:58 PST

    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.

I (Gregor) still disagree with you about this.  More in a separate
message.

    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.

Right.

    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.

Not exactly.  We think both the second paragraph of the arguments
section and the second paragraph of the remarks section should be put
under method remarks.  Briefly, the point is that a user should be free
to define a new kind of method that say doesn't have qualifiers or a new
kind of generic function which uses different congruence rules.

The value returned should be in the generic function, its has to be eq
to the first argument.

    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.  
Right
					     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.  
Right
				Maybe that detailed remark is unnecessary?
It is needed 

    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.
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).

In the current meta object draft, all those classes are (believe it or
not), subclasses of standard class.  So, this is right according to
that.  We had a long discussion with Pierre Cointe about this, that is
included in the meta-object draft we are (finally) writing.

    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.

Right, Right, Right...


    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.

Its true that this new breakout causes us to confront some meta-object
stuff which we don't really want to have to work out in the next 5 days.
But, it may be alright if we just take our best stab at it and then fix
it up later.  Here's why.  We believe that for the time being, the only
kind of programming we are really sanctioning is programming that calls
these generic functions (in cases like add-method).  In these cases, we
should take our best shot, but if in the course of writing the meta spec
we decide we need to move something from method to gf or vice versa we
can.  Because as far as the user who just calls generic functions like
add-method, the behavior of the generic function as a whole will be
unchanged.  As a point of strategy, where we are unsure, behavior should
be ascribed to the generic function rather than the one of the methods.

Generic functions like describe and print-object are different, these we
have to try and get right this go around.  Thats probably tractable,
Moon's comments above seem to hit it on the nose.
-------