Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!tut.cis.ohio-state.edu!bloom-beacon!eru!luth!sunic!Urd!newsuser From: newsuser@lth.se (LTH network news server) Newsgroups: comp.lang.c++ Subject: Re: Class documentation Keywords: c++, class, library Message-ID: <1989Oct6.080134.11338@lth.se> Date: 6 Oct 89 08:01:34 GMT References: <600@hsi86.hsi.UUCP> <4132@pegasus.ATT.COM> <662@hsi86.hsi.UUCP> Reply-To: dag@Control.LTH.Se (Dag Bruck) Organization: Dept. of Automatic Control, Lund Inst. of Technology, Sweden Lines: 194 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