Re: Documenting Individual Objects

[sdd.hp.com!ux1.cso.uiuc.edu!cs.uiuc.edu!johnson@hplabs.hpl.hp.com (Ralph Johnson)]

ron@bse.com (Ronald C. Schultz) writes:

>I am interested in tools and techniques individuals and organizations
>are using to document objects. There appears to be few, well-thought
>out and complete methods to articulate objects. Many of the existing
>methods (e.g., OMT, Wirfs-Brock, ...) concentrate on documenting 
>object-interactions, but not on documenting the objects themselves.

The reason for this is that (in my opinion) documenting a single
class is easy, and is similar to traditional function-oriented
documentation, but documenting object-interactions is much harder.
For example, in Smalltalk I am perfectly happy with class comments
and method comments as documentation for a class, but they fall apart
as documentation for how objects work together.

> d) has sufficient internal
>consistency checks and heuristics to allow me to determine if the object
>is complete, consistent, and usable. 

I don't believe that this can be done just from the documentation.

-Ralph Johnson