The author works as a computer and electronics engineer with the U.S. Department of Defense. He has nearly completed a PhD in electrical and computer engineering at Louisiana State University. His interests include computer vision, artificial intelligence, software engineering, and programming languages.
C-Doc Documentation Tools is a program that helps you document C source code on MS-DOS computers. The current version 3.2 also documents C++ programs. C-Doc requires MS-DOS 2.0 or higher, 256K of memory, and a floppy disk (a hard disk is best); it retails for $149. C-Doc searches, indexes, and cross references source code files and then presents the information in a variety of useful formats. Since C-Doc works on source code files, it will process files for virtually any C compiler. Learning how to use C-Doc is easy. Because of the variety of output formats, each programmer or group of programmers will find something in C-Doc that they need.
There exists a variety of documentation programs on the market, each of which will read your source code and then generate some type of documentation. Documentation in this context does not mean "comment lines," but rather a list of function names, parameters, variables, and function calling hierarchies. C-Doc, however, can automatically generate and insert "comment lines" into user source code, as well as producing stand-alone documentation outputs. Without such documentation programs, you must painstakingly type this information by hand. Documentation programs are especially helpful when your boss dumps a pile of strange, undocumented code into your lap and tells you to figure it out.
With 25 switches and 40 options, C-Doc is a flexible tool. C-Doc invocations range in complexity from
C-Doc filename.cto
c-Doc -a1-b40-c4-e74-f1-h1-i$-j0- k1-10-oxxxx- p60-r4 -s3-t1-w50-x35 z0 file1.c file2.c file3.c file4.cC-Doc comes with several batch files to use and modify. It also comes with a c-help program that helps you create batch files. The c-help program is a lifesaver since the many switches and options overwhelm and confuse you at first. c-help displays a menu with all the switches on a command line (see Figure 1) . Pressing the letter of a switch displays the options for that switch and what they will do. Using these explanations, writing custom batch files becomes easy.The c-help program is a good complement to the C-Doc manual. The 40-page manual is punched to fit in a small three-ring binder, but is already bound. The examples could be more thorough, but are adequate for the audience (C programmers).
With C-Doc, you can also process a list of source code files by putting the various filenames into a file and then passing that file's name to C-Doc. I used C-Doc on a program with 100 source code files and 30,000 lines of code without any problems.
C-Doc can generate eight different types of output files:
The .TOC is an alphabetical table of contents of function names. It gives the line number and file name where each function appears.
- .TOC — table of contents
- .CAL — caller/called summaries
- .TRE — graphical calling hierarchy
- .REF — all local/global/parameter variables
- .LST — code listing with line numbers and action diagrams
- .C$$ — formatted source code
- .HDR — users/calls and local/global variables by function
- .CLS — C++ class-hierarchy tree diagrams.
Figure 2 shows an example .CAL file which cross references function calling relationships. This report is helpful if you are trying to change a function call and you need to modify every instance of the call. Unfortunately in this format, using long function names pushes the entire page to the right, often resulting in extra carriage returns and wasted paper. Version 3.2 allows the selection of several space-saving formats. The output tables automatically adjust to the user-specified paper width and to the maximum length of names in the user programs.
Figure 3 shows the .TRE output, which presents the .CAL information in a graphical form (a calling hierarchy). C-Doc's graphs are not as elaborate as those of some other programs which draw boxes around the file and function names and connect them on a sideways printout.
The .REF files list all the program variables, giving each occurrence of each variable (local or global and function parameter) with the line number and file name. Options allow you to cut the otherwise copious information down to a manageable size. The new version 3.2 also does C++ class-hierarchy tree diagrams and stores the results in .CLS files.
Unlike some documentation tools, C-Doc also acts as a pretty printer. Figure 5 shows how C-Doc reformats the code in Figure 4 into a more readable style. Version 3.2 can reformat source code into several different standardized formats. Figure 6 shows formatted coded with "action diagrams" inserted. Action diagrams use single lines to outline logic constructs and uses double lines to outline loops. The action diagrams can be helpful in deciphering particularly messy code written by someone else. C-Doc can also line number the source and put its outputs into one long .LST file or into .C$$ files. The .C$$ files have the same file name but with the .C$$ extension, preventing any accidental damage to the original source code.
Figure 7 shows a .HDR file, a combination of .CAL and .REF outputs which gives the user/calls and all variables for each function. C-Doc can take this information, split it up, and insert the documentation for each function into the source code just before the function itself. This is one of the best features of C-Doc.
C-Doc does have some annoying characteristics. First, it places the output on the left edge of the page when printing. If you place your paper in a three ring binder, you lose a few words here and there. I wrote a program that tabs the words over to the right before printing, but C-Doc should be able to do this by itself.
Second, the C-Doc status display uses a black background with several different colored letters. There is no method of changing the display colors, some of which can be painful to stare at. However, version 3.2 does allow the user to select monochrome (black and white) or color for the status display.
On balance, C-Doc is practical, affordable, and useful. If you write large C programs spread over dozens of files, if you are part of a programming team or manage a programming team, if you work in a lab or a shop where programmers come and go, then you can make productive use of C-Doc.