Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!mailrus!shadooby!ginosko!uunet!hsi!wright
From: wright@hsi.UUCP (Gary Wright)
Newsgroups: comp.lang.c++
Subject: Re: Class documentation
Keywords: c++, class, library
Message-ID: <674@hsi86.hsi.UUCP>
Date: 9 Oct 89 14:56:18 GMT
References: <600@hsi86.hsi.UUCP> <4132@pegasus.ATT.COM> <662@hsi86.hsi.UUCP> <4148@pegasus.ATT.COM>
Reply-To: wright@hsi.com (Gary Wright)
Organization: Health Systems Intl., New Haven, CT.
Lines: 41

In article <4148@pegasus.ATT.COM> psrc@pegasus.ATT.COM (Paul S. R. Chisholm) writes:

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

If the design of the interface is the product, why is there such a vast
difference in price between a reference manual and the implementation?

Perhaps "sales literature" was a bad choice of words.  I would
like to have a way to examine a class without purchasing the entire 
"reference manual".  Some sort of documentation that fills the gap
between sales literature and a reference manual is what I am looking
for.  If this is not feasible, why not?

Assuming that we are talking about documentaion at the level of
"reference manual", Dag M. Bruck in <1989Oct6.080134.11338@lth.se>
provided an interesting example of "automated" documentation.  At a
minimum, perhaps some standard man page headings can be proposed.  Part
of the problem is that even within a class, the description of a member
function tends to be quite informal.  The use of pre-conditions,
post-conditions and invariants in Eiffel to describe a class and its
routines leads to documentation that is concise and to the point.
Comments can be used to describe a condition that is
computationally expensive or difficult to describe formally.  While
Eiffel supports these notions in the language itself, there is no
reason why the technique can not be used in any language including
C++.

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

It is too bad that there aren't de-facto standardized C++ classes.
C++ is in desperate need of a standard data structures library so that
programmers do not need to post to the net to see if anybody has a
{list, graph, stack} class they could use.
-- 
Gary Wright 					...!uunet!hsi!wright
Health Systems International                    wright@hsi.com