Documenting an OO class library

[Susan Gallagher <75462 -dot- 3613 -at- COMPUSERVE -dot- COM>]

Colleen Pars is looking for an effective way to document Smalltalk classes. I
documented a Smalltalk-based application development environment (Enfin) for two
years. For what it's worth, this is what we did.

Class Descriptions:
For each class, the Smalltalk programmer needs to know its position in the class
hierarchy (i.e., superclass and subclasses) and a description of the class (why
it was created, what it is meant to do, whether it is abstract, etc.) including
any limitations to the class (e.g., class String can only contain objects of
class Character).

Method Descriptions:
For each method within the class, the programmer needs to know whether it's a
class method or an instance method and if it's a callback method (methods that
are triggered automatically as forms open and close, etc.).

Information that we included for each method:
Method name -- including syntax (e.g. rather than giving the method name
"visibleTablesAt:put:", use  "ExternalDatabase visibleTablesAt: databaseName
put: array" )
Description -- a paragraph that states what the method is supposed to do.
Assumptions -- many Smalltalk methods make assumptions as to the data type of
parameters. If put: expects an array of symbols and gets an array of integers or
strings, things won't function as expected, so let the programmer know what the
method expects to see.
Return value -- once the processing is done, what does the method "spit out"?
Receiver modified: whether the method modifies the receiver or leaves it as it
was

Where do you get this information?  Hopefully, you'll develop a **really** good
relationship with the programmers. They're the only ones that can tell you what
they've programmed and what they've changed. Maintainability was our biggest
problem at Enfin. We never knew what methods had changed, and, since the
programmers were not always encouraged to document their changes, methods often
went out with incorrect documentation (or none at all).

What Smalltalk system are you using? Do you have access to the Class Browser?
Can you mimic the documentation method that came with the system? This approach
will often be the most beneficial for programmers (who are your end-users)
because they'll be able to get all the information they need in one format.

I've posted to the list because there seemed to be some peripheral interest.
Feel free to post or call me if you need more information.

Sue Gallagher
Technical Writer
StarBase Corp, Irvine CA
sgallagher -at- starbasecorp -dot- com OR 75462 -dot- 3613 -at- compuserve -dot- com OR (714) 442-4458