Class comments (was Re: ProtoObject?)

R. A. Harmon harmonra at webname.com
Thu Feb 10 16:15:39 UTC 2000


At 06:12 PM 2/9/00 -0800, Dan Ingalls wrote:
>Stefan Matthias Aust <sma at 3plus4.de> (and not I -- sorry) wrote...
>
>>However, we should first agree upon a common format.
>
>Here is a first crack at this, both as a template for criticism and
suggestions, and as a piece of code you can try out.  I had some fun today
trying to generate the structure with types automatically (that was the
heh-heh), and, as type inference workers are used to saying, "It turned out
to be harder than I thought." (*).
[snip]
>(*) Actually it was easy, it just didn't do quite as well as I had hoped.
>If anyone is interested I can send you the code.
>It collects all selectors sent to each instVar, and then computes the
>union of highest classes that implement that full set.
>I think that with info from stores, and possibly == tests, it would do a
lot better.

As part of creating unit tests for the ANSI messages, I implemented protocol
and message specification classes like protocols are used in "Draft American
National Standard for Information Systems - Programming Languages -
Smalltalk".  This is mainly used to check that a result conforms to the
return type specified with an assertion.

Protocol support the "Conforms To", "Description", etc.  Message
specifications support the "Synopsis", "Definition:", "Parameters", "Return
Value", "Errors", "Rationale", etc.  I hope in the future to use this
protocol support to document my applications, goodies, whatever.

Documenting methods using protocols has a number of advantages.  One of them
is that in the current system you must either comment a method once in the
class where it is specified (Object>>#hash) and refer back to this in method
comments that redefine it, or duplicate the comment in each.  Another is
that there are a large body of examples in the new standard.

I suggest my protocols approach may be a useful in documenting Squeak.
Comments pro or con welcome.


Protocol as objects also has the advantage that they may be used in testing.

I also followed Dolphin Smalltalks example of allowing the protocol objects
to be removed but still allow classes to retain their protocol names.

Anyone interested in further information or to try out my protocols can
download an alpha/experimental/proof of concept/needs work version for
Squeak 2.6 at my web page:

        http://homepage2.rconnect.com/raharmon/


As additional background I'd note that I added some assertion methods to
SUnits to test that a result conforms to the return type specified which
take as parameters the protocol name and the message selector.  For messages
that need a rule, the receiver (and the operand).  The operation block of
the assertion will result in the object returned.  Examples (of just a
couple of them):

     self
        op: [2.1 floor]
        should: [:r | r = 2]
        conformTo: #'number'
        selector: #'floor'.

    self
        op: [float2 / 2]
        should: [:r | r closeTo: (retVals at: numTypeNdx)]
        conformTo: #'number'
        selector: #'/'
        ruleReceiver: float2
        operand: 2

--
Richard A. Harmon          "The only good zombie is a dead zombie"
harmonra at webname.com           E. G. McCarthy
Spencer, Iowa





More information about the Squeak-dev mailing list