Path: utzoo!attcan!uunet!wuarchive!psuvax1!rutgers!att!dptg!pegasus!psrc
From: psrc@pegasus.ATT.COM (Paul S. R. Chisholm)
Newsgroups: comp.lang.c++
Subject: Re: Class documentation
Keywords: c++, class, library
Message-ID: <4148@pegasus.ATT.COM>
Date: 8 Oct 89 22:19:07 GMT
References: <600@hsi86.hsi.UUCP> <4132@pegasus.ATT.COM> <662@hsi86.hsi.UUCP>
Organization: AT&T Bell Laboratories
Lines: 52

In article <662@hsi86.hsi.UUCP>, wright@hsi.UUCP (Gary Wright) asks how
to document a C++ class.  The solution we've used in AT&T (and here I
speak as a customer, not as a producer) is to either:

o  write a manual page for the whole class, with all public (and maybe
protected?) member variables and functions, and giving references to
friend functions; or

o  write a manual page for the class, with a general overview, and
references to other manual pages.  For example, cplx.intro(3C++) has a
few words about description and diagnosis, and says to see also
cartpol(3C++), cplxerr(3C++), cplxops(3C++), and cplxtrig(3C++).

There's usually a tutorial floating around somewhere, too.

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

Excuse me?  The interface description is *not* "sales literature."  The
design of the interface, as much or more than the implementation of the
classes, is the *product*.  That's true of third party C function
libraries today.

I don't see a time where there'll be standardized C++ classes, and lots
of competition to provide them.  If a class is standardized, the
language processor vendor will probably supply it.

(Even when class interfaces are standardized, user documentation will
always be part of the total product.  When the ANSI C standard is
finally made official, you'll be able to get a copy of the standard
for a few bucks; but you won't be able to call Microsoft and say, "I'm
interested in your C compiler's library.  Could you please send me the
reference manual?")

> Gary Wright 					...!uunet!hsi!wright
> Health Systems International                    wright@hsi.com

Paul S. R. Chisholm, AT&T Bell Laboratories
att!pegasus!psrc, psrc@pegasus.att.com, AT&T Mail !psrchisholm
I'm not speaking for the company, I'm just speaking my mind.