Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!mailrus!wuarchive!wugate!uunet!hsi!wright
From: wright@hsi.UUCP (Gary Wright)
Newsgroups: comp.lang.c++
Subject: Class documentation
Keywords: c++, class, library
Message-ID: <662@hsi86.hsi.UUCP>
Date: 5 Oct 89 13:44:08 GMT
References: <600@hsi86.hsi.UUCP> <4132@pegasus.ATT.COM>
Reply-To: wright@hsi.com (Gary Wright)
Organization: Health Systems Intl., New Haven, CT.
Lines: 40

I have recently been trying to learn about the various C++ class libraries
that are available (NIH, ET++, Interviews, CommonView) and have found little 
or no documentation that I would find helpful.  Instead, I have had to
examine the code itself.

For software to become truly reusable, I should be able to pick up a
catalog or read an on-line document that describes the complete
interface to a class.  In this way, I can determine if the class will
meet my needs without having to purchase the implementation.

This would require that there be a standard way of documenting the
interface to a class.  In C++, some form of the .h file for the class
would seem appropriate.  Unfortunately, simply using the .h file is not
a solution.  Private details of the class are not hidden, and the lack
of helpful comments (at least in the class headers I have examined in
NIH and ET++) makes the header file almost useless.  The extremely
terse coding style that C and C++ promotes does not help in providing
clear documentation either.

Has anybody developed an automated method for producing helpful and
*readable* class interface documentation?

In article <4132@pegasus.ATT.COM> 
psrc@pegasus.ATT.COM (Paul S. R. Chisholm) writes:
>If you want more information, you should order the appropriate C++
>Language System Release 2.0 documents:
>	Reference Manual: $25, select code 307-146
>	Library Manual: $35, select code 307-145
> 	Selected Readings: $30, select code 307-144
>	Release Notes: $20, select code 307-090

This seems to be a partial solution. I still would like to be able to
call AT&T, and say "I am interested in your complex arithmetic
classes.  Could you please send me the interface description for them?"
If we really want to create an environment in which classes can be
purchased from any number of suppliers the customer should not be
expected to pay for the sales literature.
-- 
Gary Wright 					...!uunet!hsi!wright
Health Systems International                    wright@hsi.com