wright@hsi.UUCP (Gary Wright) (10/05/89)
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
newsuser@lth.se (LTH network news server) (10/06/89)
In article <662@hsi86.hsi.UUCP> wright@hsi.com (Gary Wright) writes: >Has anybody developed an automated method for producing helpful and >*readable* class interface documentation? Yes, I have written a AWK program that produces a standard UNIX man-page from a C++ header file. It will format and to some degree rearrange the contents of the .h file, but it is not supposed to throw away anything. The parsing is *very* simple and requires a certain programming style. For example, a class definition must start with the keyword `class' as the first word of a line, and the class must end with `};' on a separate line. The AWK program has evolved from my private programming style (and works very well), but it does not handle every legal C++ program. I have enclosed a small example below. It looks nicer if printed on a laser printer, of course. The program (called `classdoc') is available free of charge and warranty. Please note that it is written for the `new' AWK or the GNU look-alike `gawk'. The old standard AWK does not have functions, for example. Comments are gratefully accepted. Source file: ================================================================ // This is a generic list package in C++. Any kind of object can be the // member of such a list, but specialized list types are normally created for // each type of object. An element can be the member of many lists at a time. // Before an object is destructed, it must explicitly be taken out of any lists // (otherwise there will be pointers left pointing to deallocated space). // // .SS Performance // The list is implemented as an array of pointers. // Inserting elements at the front of the list (Insert) // is cheap; removing elements (except the first) and inserting at the end // is more expensive. Assignment and passing a list as a VALUE parameter // requires copying of the pointer array, and is therefore expensive; pass // lists as "const reference" parameters instead. // // .SS History // Author: Dag Bruck. #ifndef LIST_H #define LIST_H #include "defs.H" typedef void* Pointer; class GenericList { friend class GenericIterator; public: GenericList(); // Constructs a list with no elements. ~GenericList(); // Destructs list. The elements in the list are not // destructed. void Insert(Pointer); // Inserts an element first in list. void Append(Pointer); // Inserts an element last in list. Not as efficient as Insert(). void Remove(Pointer); // Removes an element from list. The element is not destructed. // It is o.k. to remove an element which is not a member of the list. unsigned Length(); // Returns the number of elements in list. GenericList(const GenericList&); // Used for passing parameters and return values. private: Pointer* p; // Array of pointers to actual member objects. unsigned n; // Number of elements in list. unsigned size; // Maximum number of elements in list. }; inline unsigned GenericList :: Length() { return n; } #endif Documentation: ============================================================== lis.H(C++) lis.H(C++) DESCRIPTION This is a generic list package in C++. Any kind of object can be the member of such a list, but specialized list types are normally created for each type of object. An element can be the member of many lists at a time. Before an object is destructed, it must explicitly be taken out of any lists (otherwise there will be pointers left pointing to deallo- cated space). Performance The list is implemented as an array of pointers. Inserting elements at the front of the list (Insert) is cheap; remov- ing elements (except the first) and inserting at the end is more expensive. Assignment and passing a list as a VALUE parameter requires copying of the pointer array, and is therefore expensive; pass lists as "const reference" parame- ters instead. History Author: Dag Bruck. CLASS GenericList Friends class GenericIterator; Public members GenericList(); Constructs a list with no elements. ~GenericList(); Destructs list. The elements in the list are not des- tructed. void Insert(Pointer); Inserts an element first in list. void Append(Pointer); Inserts an element last in list. Not as efficient as Insert(). void Remove(Pointer); Removes an element from list. The element is not des- tructed. It is o.k. to remove an element which is not a member of the list. unsigned Length(); Returns the number of elements in list. GenericList(const GenericList&); Used for passing parameters and return values. Private members Pointer* p; Array of pointers to actual member objects. unsigned n; Number of elements in list. unsigned size; Maximum number of elements in list. CODE inline unsigned GenericList :: Length() { return n; } TYPE DEFINITIONS void* Pointer; DEFINED MACROS LIST_H INCLUDED FILES defs.H ClassDoc 2.1 Last change: Oct 6 09:00 2 ------------------------------- Dag M. Bruck -- Department of Automatic Control Internet: dag@control.lth.se Lund Institute of Technology P. O. Box 118 Phone: +46 46-108779 S-221 00 Lund, SWEDEN Fax: +46 46-138118
jima@hplsla.HP.COM (Jim Adcock) (10/07/89)
I don't know about "automatically" generating the documentation, but most helpful for me is to have on-line unix-style manual pages. If one is serious about writing reusable classes, one ought to at least have the motivation to write a manual page on them. One shouldn't have to read code to figure out how to use someone else's classes. And PLEASE name your manual page after your class name. I can't tell you how tired I get of failing on "man complex" and then having to search my file system to find what gd manual page name the info on the complex classes is stored under.
psrc@pegasus.ATT.COM (Paul S. R. Chisholm) (10/09/89)
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.
wright@hsi.UUCP (Gary Wright) (10/09/89)
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
jima@hplsla.HP.COM (Jim Adcock) (10/10/89)
>(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?") I won't have to call Microsoft. I'll just look it up using on-line searches of their CD-ROM documentation. I think more and more companies are going to head towards CD-ROMS for publishing their software and/or documentation en mass, and what people will be paying for is a "license to use" with maybe an attached password. Hopefully, programmers will not continue to be stuck with "shrink-wrap" licensing that prevents you from even reading about the product before you buy it. This really sucks. Also, I refuse to accept the idea that the design of a class interface represents a unique marketable product. This would allow companies to fragment the C++ user community by locking software writers into a particular vendor's C++ libraries. Customers and competitors need to be able to design "work-alike" libraries, or we're never going to get anywhere with "software reusability." C++ customers need to be able to use the same core set of libraries whether writing on MS-DOS, un*x, cloniks, portables, transportable, minis, mainframes, or supers.