diff options
Diffstat (limited to 'C++autodoc')
| -rw-r--r-- | C++autodoc | 292 |
1 files changed, 292 insertions, 0 deletions
diff --git a/C++autodoc b/C++autodoc new file mode 100644 index 0000000..468f1dd --- /dev/null +++ b/C++autodoc @@ -0,0 +1,292 @@ +From greyham Thu Oct 28 18:42:35 1993 +Newsgroups: comp.lang.c++,comp.programming.literate +Subject: An Automatic C++ documentation compilation project. +Summary: Anyone willing to add C++ support to c2man? +Keywords: c2man, C, C++, Literate Programming, Documentation + +Copyright 1993, 1994 by Graham Stoney. +This may be freely redistributed or quoted, so long as it's attributed to me. + +Writing and maintaining documentation has often been a thorn in the side of the +Software Engineer and Programmer. After spending a great deal of time and +effort writing documentation about a program or software system, the code +invariably changes, quickly rendering the documentation out of date. The +documentation becomes misleading, gets neglected, and quickly becomes useless. + +"Literate Programming" is one approach to solving this problem. It effectively +introduces a whole new (typesetting) language, requires a quite radical shift +on the part of the "non-literate" programmer and still requires a good deal of +effort on the part of the programmer[1]. + +I'd like to suggest a different approach which lies considerably closer to +more traditional programming practices, and can offer quite immediate benefits +when functional interface documentation is the main documentation required. + +The primary philosophy here is to use the programming language as far as +possible to express the programmer's intentions, and to use comments only when +the programming language is not sufficiently expressive. A comment can then +become part of the language grammar which is recognised by a "documentation +compiler". This tool parses a superset of the programming language and can +automatically generate documentation in human-readable form by associating the +programmer's comments with the objects in the code by their context. + +Whilst the idea of extracting documentation from comments in source code is by +no means new, the difference here is that the comments actually form part of +the grammar of the language recognised by the documentation compiler[2]. + +Comments should not repeat information that is already represented in the +program code; for instance, a comment describing a function argument should not +repeat the name and type of that argument (since that information has already +been included, for the compiler), but should appear near the argument. + +For example, in C, the programmer should write this: + + /* include an example in the article */ + enum Result example(int page /* page it appears on */); + +Rather than this: + + /* include an example in the article + * + * PARAMETERS: + * int page page it appears on + * + * RETURNS: + * RESULT_YES The readers agreed + * RESULT_NO The readers disagreed + * RESULT_YOURE_JOKING The readers disagreed strongly + * RESULT_BLANK_LOOKS The readers didn't understand + */ + enum Result example(int page); + + +Also in this example, the documentation compiler knows the possible enumerated +values that the function can return (as does the "real" compiler), so it is +unnecessary for the programmer to restate them. The comments need simply be +included in the definition for "enum Result" for the "RETURNS" information to +be generated automatically: + + enum Result { + RESULT_YES, /* The readers agreed */ + RESULT_NO, /* The readers disagreed */ + RESULT_YOURE_JOKING, /* The readers disagreed strongly */ + RESULT_BLANK_LOOKS /* The readers didn't understand */ + }; + +Critics have suggested that the latter style in the example is easier to read +for someone wishing to call the function in question. Of course, this is a +style question which depends on each person's tastes; but the criticism is tied +to the notion that the source code needs to look "beautiful" because it is the +primary reference for someone wishing to use that function. This becomes much +less significant once documentation is available which is known to _always_ be +up to date. Of course, the latter style takes longer to write and maintain, +and can become out of date should the name or type of the parameter be +changed, yet the comment get neglected. + +I have implemented one such documentation compiler for the C language called +"c2man", which is freely available[3]. The response from users has been +extremely encouraging; I suspect this is partly because of the wide variety of +styles of comment placement that are recognised: it often correctly recognises +comments that weren't written with c2man in mind at all. While it's use is +focused solely on functional interface documentation and it doesn't have +anywhere near the power of a full Literate Programming system, the focus is on +reducing the effort required by the programmer to the absolute minimum, and +seeing how much documentation we can get essentially "for free". + +Many people have requested C++ support be added to c2man, and I suspect that +this philosophy would be even more suitable and powerful for documenting +interfaces to C++ classes automatically. + +Here is an example of how I envisage this philosophy would work when applied to +C++. It's interesting to note that this code was written a couple of years ago +exactly as you see it here, without the idea of generating documentation from +it in mind at all: + + + // generic Timer class + class Timer + { + private: + static int numactive; // number of constructed timers. + static Timer *first; // first one in list. + Timer *next; // next one in linked list. + Time ticksdiff; // ticks we take to expire once at front. + + enum + { + INACTIVE, // timer is not in chain. + STARTED, // one-shot + RUNNING // continuous. + } state; + + // original interrupt vector value. + static void interrupt (far *old_vector)(...); + + void (*timeout_function)(int); // function called when we time out + int timeout_parameter; // gets passed to timeout_function + Time duration; // timer length (ticks) + + static void interrupt far tick(...); // clock tick routine. + + void insert(); // add into active chain. + void remove(); // remove from active chain. + void set(Time milliseconds); // set duration from ms. + + public: + // constructor + Timer(Time time=0, // milliseconds + void (*function)(int)=0, // called at timeout + int param=-1); // param for function + + // destructor + ~Timer(); + + // start (or restart) a timer running. + void Start(); + void Start(Time duration); // how long to run for + + // start a timer running continuous. + void Run(); + + // stop a timer. + void Stop(); + + // is a timer active? + boolean Active() const { return state != INACTIVE; }; + }; + + +Processing this class declaration could generate the following automatically: + + NAME + Timer - generic timer class + + SYNOPSIS + class Timer + { + public: + Timer(Time time=0, + void (*function)(int)=0, + int param=-1); + ~Timer(); + void Start(); + void Start(Time duration); + void Run(); + void Stop(); + boolean Active() const; + }; + + PARAMETERS + Time time + Milliseconds + + void (*function)(int) + called at timeout. + + int param + Param for function. + + Time duration + How long to run for. + + DESCRIPTION + Timer + Constructor + + ~Timer + Destructor + + Start + Start (or restart) a timer running. + + Run + Start a timer running continuous. + + Stop + Stop a timer. + + Active + Is a timer active?. + + +It should also be possible to extract this information from the implementation +of the class (rather than the declaration), if that's where the user prefers to +put the comments describing each member function and their parameters. + +The ideal tool should: +1. Avoid imposing a style on the programmer. +2. Work out section names (NAME, SYNOPSIS etc) without the programmer having + to specify them explicitly. +3. Handle C++ and C style code equally well. +4. Not require the programmer to restate information which is already expressed + in the syntax of the programming language. +5. Work reasonably well with existing code. +6. Flatten the class hierarchy so that the documentation for each class + includes virtually everything the user needs to know about it. + +A number of tools already exist which attempt to tackle this problem, such as +class2man, genman, classdoc and docclass. They vary in sophistication, +utility, and the demands they place on the programmer; however, none as yet +meet all the criteria set out above, and no one tool will suit the tastes of +all programmers. + +Pouring lots of effort into a really ``smart'' documentation generator makes +sense because once it's done, you get a payback for every document you +generate. Every little feature added to the documentation generator to make +things easier for the programmer pays off multiple times, and minimising the +effort required by the programmer is the key. + +The logical starting point would be to graft Jim Roskind's C++ grammar[4] into +c2man, modifying it to recognise comments in the relevant places, and adding +all the necessary structures to hold the information from the parser that will +get included in the output. Very little functional change should be needed in +the lexer, which already recognises C++ comments. + +Unfortunately, at present I do not have sufficient spare time to make the +additions to c2man required to support C++. It would be a great contribution to +the C++ community, not to mention the documentation time saved by themselves, +for someone involved in C++ work to add this support and release the result[5]. + +If you work with a team developing C++ code, please consider having one of your +developers on a ``Usenet Sabbatical'' to extend this philosophy to C++, and +start reaping the benefits in documentation time savings. + +It could also make an ideal Computer Science student compiler project. + +Please contact me via E-mail if you are interested in undertaking such a +project. + + +Graham Stoney +greyham@research.canon.com.au + +Footnotes: +1. Advocates of Literate Programming would argue that Literate Programming is + much more than snazzy documents and that it encourages this extra effort to + focus early on in the design of the software, which pays off later. + +2. To get a better idea, see the file grammar.y in the c2man distribution. + +3. c2man has been posted to comp.sources.misc. It should be available from: +location: ftp from any comp.sources.misc archive, in volume42 + (the version in the comp.sources.reviewed archive is obsolete) + ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl + Australia: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* + from archie.au + N.America: ftp /usenet/comp.sources.misc/volume42/c2man-2.0/* + from ftp.wustl.edu + Europe: ftp /News/comp.sources.misc/volume42/c2man-2.0/* + from ftp.irisa.fr + Japan: ftp /pub/NetNews/comp.sources.misc/volume42/c2man-2.0/* + from ftp.iij.ad.jp + Patches: ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se + +4. Jim Roskind's yaccable C++ grammar is available via ftp from + ics.uci.edu in the ftp/pub directory as: + + c++grammar2.0.tar.Z + byacc1.8.tar.Z + +5. c2man's copyright requires that all derivative works remain freely + available. + |